updating subhosting documentation (#436)

sidebars/subhosting.js

@@ -1,20 +1,48 @@
 const sidebars = {
-  subhosting: [
+  subhosting: [],
+
+  subhostGuideHome: [
     {
       type: "html",
       value: "<div>Getting Started</div>",
       className: "section-header",
     },
-    "manual/index",
-    "manual/getting_started",
-    "manual/projects_and_deployments",
-    "manual/events",
+    {
+      type: "doc",
+      label: "About Subhosting",
+      id: "manual/index",
+    },
+    {
+      type: "doc",
+      label: "Quick Start",
+      id: "manual/quick_start",
+    },
+    {
+      type: "doc",
+      label: "Planning your implementation",
+      id: "manual/planning_your_implementation",
+    },
+    {
+      type: "doc",
+      label: "Pricing and Limits",
+      id: "manual/pricing_and_limits",
+    },
     {
       type: "html",
       value: "<div>REST API</div>",
       className: "section-header",
     },
-    "api/index",
+    {
+      type: "doc",
+      label: "Resources",
+      id: "api/index",
+    },
+    {
+      type: "doc",
+      label: "Authentication",
+      id: "api/authentication",
+    },
+    "manual/events",
     {
       type: "link",
       label: "API Reference Docs",

subhosting/api/authentication.md

@@ -0,0 +1,44 @@
+# Authentication
+
+Developers can provision projects, domains, KV databases, and other resources
+using the Subhosting REST API.
+
+## Endpoint and authentication
+
+The base URL for the Subhosting REST API v1 is below.
+
+```console
+https://api.deno.com/v1/
+```
+
+The v1 API uses
+[HTTP bearer token](https://swagger.io/docs/specification/authentication/bearer-authentication/)
+authentication. You can create an access token to use the API in the dashboard
+[here](https://dash.deno.com/account#access-tokens). Most API requests will also
+require your organization ID. You can retrieve yours from the Deno Deploy
+dashboard for your organization.
+
+![Find your org ID here](./images/org-id.png)
+
+Using both your organization ID and your access token, you can test your API
+access by listing all the projects associated with your organization. Here is an
+example Deno script you can use to access the API.
+
+```typescript
+// Replace these with your own!
+const organizationId = "a75a9caa-b8ac-47b3-a423-3f2077c58731";
+const token = "ddo_u7mo08lBNHm8GMGLhtrEVfcgBsCuSp36dumX";
+
+const res = await fetch(
+  `https://api.deno.com/v1/organizations/${organizationId}/projects`,
+  {
+    method: "GET",
+    headers: {
+      Authorization: `Bearer ${token}`,
+    },
+  },
+);
+
+const response = await res.json();
+console.log(response);
+```

subhosting/api/index.md

@@ -1,47 +1,128 @@
-# Subhosting REST API
+# Subhosting Resources
 
-Developers can provision projects, domains, KV databases, and other resources
-using the Subhosting REST API.
+To build Subhosting with Deno Deploy, it helps to understand some key resources
+within the system. These resources are also represented in the
+[REST API](../api/index.md).
 
-## Endpoint and authentication
+![overview of subhosting resources](./images/subhosting-org-structure.svg)
 
-The base URL for the Subhosting REST API v1 is below.
+<a id="organizations"></a>
 
-```console
-https://api.deno.com/v1/
-```
+## Organizations
+
+[**Organizations**](https://apidocs.deno.com/#get-/organizations/-organizationId-)
+are a container for all data related to a subhosting implementation. Your
+organization will have a name and an ID. Each organization has an analytics
+endpoint which can be used to get metrics (such as request count and bandwidth
+used) from across the organization.
+
+Other Deploy users can be invited to collaborate on an organization, and
+[access tokens](https://dash.deno.com/account#access-tokens) can give developers
+with organization access the ability to modify resources within the org via API.
+New organizations can be created in the
+[Deploy dashboard](https://dash.deno.com/orgs/new).
+
+<a id="projects"></a>
+
+## Projects
+
+[**Projects**](https://apidocs.deno.com/#get-/organizations/-organizationId-/projects)
+act as organizational containers for deployments. A project contains its
+deployments and the analytics and usage information for those deployments.
+
+Projects are free and can be set up as required.
+
+To track usage by individual users for billing there is an API endpoint that
+reports analytics (bandwidth usage, request count, etc), per project, with 15
+minute granularity.
+
+> All deployments (whether within a same project or between different projects)
+> share nothing by default. Projects are a way to organize your deployments and
+> do not cost anything. However analytics are reported on a per-project basis,
+> if you have multiple tenants we recommend setting up a project for each.
+> Particularly if you expect to bill your users for their usage.
+
+<a id="deployments"></a>
+
+## Deployments
+
+[**Deployments**](https://apidocs.deno.com/#get-/projects/-projectId-/deployments):
+a deployment is a set of configuration, runnable code, and supporting static
+files that can run on an isolate in Deno Deploy. Deployments have an entry file
+that can launch a server, can have a [Deno KV](/deploy/kv/manual) database
+associated with them, and can be set up to run on custom domains.
+
+A deployment is an immutable object that consists of:
+
+- Source code to run
+- Static assets
+- Environment variables
+- Database bindings
+- Other settings
+
+We provide endpoints for querying or streaming build logs and querying or
+streaming execution logs.
+
+If you need to block or unblock a deployment you can do so by deleting the
+deployment that you need to block or by unassigning its domains. This will make
+the deployment unreachable.
+
+The Subhosting system is built so that the behavior or load on one deployment
+does not affect other deployments. This also applies to different deployments
+within one organization. Capacity is auto-scaled on demand. If you want to limit
+resources to a particular deployment or application you can use the analytics
+API to provide you with detailed metrics (request count, bandwidth, etc) at
+project level granularity. You can use this to decide whether to shut off
+deployments and make them unreachable.
+
+> NB. **Deployments are immutable**, however, you can create a new deployment
+> and then remap its domain to the new deployment. The redeploy endpoint can
+> create a new deployment from an existing one with different settings.
+
+<a id="domains"></a>
+
+## Custom domains
+
+[**Custom domains**](https://apidocs.deno.com/#get-/organizations/-organizationId-/domains)
+can be dynamically mapped to deployments, giving them a unique URL (eg
+`mycompany.com`).
+
+Before a domain can be used you need to
+[verify ownership and provision
+or upload TLS certificates](https://github.com/denoland/deploy-api/blob/main/samples.ipynb).
+
+If you are on the [Builder tier](https://deno.com/deploy/pricing?subhosting) you
+can use wildcard domains. Once you have a wildcard domain registered, you can
+use it in two ways:
+
+- Send all requests for `*.mycompany.com` to a specific deployment
+- (Coming soon) Assign different subdomains (e.g. `foo.mycompany.com` and
+  `bar.mycompany.com`) to separate deployments.
+
+### Staging vs Production Environments
+
+The Deno Deploy end-user platform automatically creates preview deployments when
+a developer opens a github pull request, and commits to the “main” branch are
+automatically turned into production deployments. Although subhosting does not
+provide github integration out of the box, it has all the primitives you need to
+define your own semantics for creating preview and production deployments.
+
+<a id="database"></a>
+
+## Connecting a KV Database
+
+A (KV) database stores key-value pairs You can make a database accessible to a
+deployment when you make the deployment. KV databases can be used by multiple
+deployments at the same time.
+
+To use KV with Subhosting:
+
+- [Create a database using the API](https://docs.deno.com/deploy/kv/manual)
+- When you create a deployment using the Subhosting API, specify the database
+  you created.
+
+> NB. Deno Cron and Queues do not currently work for Subhosting.
 
-The v1 API uses
-[HTTP bearer token](https://swagger.io/docs/specification/authentication/bearer-authentication/)
-authentication. You can create an access token to use the API in the dashboard
-[here](https://dash.deno.com/account#access-tokens). Most API requests will also
-require your organization ID. You can retrieve yours from the Deno Deploy
-dashboard for your organization.
-
-![Find your org ID here](./images/org-id.png)
-
-Using both your organization ID and your access token, you can test your API
-access by listing all the projects associated with your organization. Here is an
-example Deno script you can use to access the API.
-
-```typescript
-// Replace these with your own!
-const organizationId = "a75a9caa-b8ac-47b3-a423-3f2077c58731";
-const token = "ddo_u7mo08lBNHm8GMGLhtrEVfcgBsCuSp36dumX";
-
-const res = await fetch(
-  `https://api.deno.com/v1/organizations/${organizationId}/projects`,
-  {
-    method: "GET",
-    headers: {
-      Authorization: `Bearer ${token}`,
-    },
-  },
-);
-
-const response = await res.json();
-console.log(response);
-```
 
 ## OpenAPI specification and tooling
 

subhosting/manual/acceptable_use_policy.md

@@ -0,0 +1,30 @@
+# Acceptable use policy
+
+The Deno Subhosting service includes resources (CPU time, request counts) that
+are subject to this Acceptable Use policy. This document can give a rough
+estimate to what we consider as "Acceptable Use", and what we do not.
+
+### Examples of Acceptable Use
+
+- ✅ Server-side rendered websites
+- ✅ Jamstack sites and apps
+- ✅ Single page applications
+- ✅ APIs that query a DB or external API
+- ✅ A personal blog
+- ✅ A company website
+- ✅ An e-commerce site
+
+### Not Acceptable Use
+
+- ❌ Crypto mining
+- ❌ Highly CPU-intensive load (e.g. machine learning)
+- ❌ Media hosting for external sites
+- ❌ Scrapers
+- ❌ Proxy or VPN
+
+## Guidelines
+
+We expect most projects to fall well within the usage limits. We will notify you
+if your projects usage significantly deviates from the norm. We will reach out
+to you where possible before taking any action to address unreasonable burdens
+on our infrastructure.