Merge pull request #155 from suborbital/laura/update-scn-docs

Author: Laura Langdon

.github/workflows/documentation.yml

@@ -13,9 +13,7 @@ jobs:
       - uses: actions/checkout@v1
       - uses: actions/setup-node@v1
         with:
-          node-version: '14'
-      - name: Upgrade NPM
-        run: npm install -g npm
+          node-version: '>=16'
         # see https://github.com/bahmutov/npm-install/issues/103#issuecomment-931226602
       - name: Test Build
         env:

.gitignore

@@ -8,5 +8,6 @@ website/yarn.lock
 **/.DS_Store
 
 .vscode
+.idea
 build
 dictionary.dic

spelling.dic

@@ -86,6 +86,8 @@ deployable
 deployDraft
 desiredmessage
 dev
+devs
+Devs
 devgenius
 dir
 Distroless
@@ -146,6 +148,7 @@ GetStaticFile
 getTemplate
 gettingStarted
 getToken
+gettoken
 getUsers
 GggP
 ghstars

website/docs/assets/editor-screen.png

@@ -1,3 +1,7 @@
+---
+pagination_next: null
+---
+
 # Static Directory
 
 An Atmo project can optionally contain a `static` directory. When present,

website/docs/atmo/concepts/static-directory.md

@@ -1,3 +1,7 @@
+---
+pagination_next: null
+---
+
 import Tabs from '@theme/Tabs';
 import TabItem from '@theme/TabItem';
 import { MultiLanguageCodeBlock } from '@site/extensions/mlc.jsx'

website/docs/atmo/runnable-api/file.md

@@ -1,3 +1,7 @@
+---
+pagination_prev: null
+---
+
 # Introduction to the Runnable API
 
 import { MultiLanguageCodeBlock } from '@site/extensions/mlc.jsx'

website/docs/atmo/runnable-api/introduction.md

@@ -1,3 +1,7 @@
+---
+pagination_next: null
+---
+
 # Connections
 
 In order to build a useful application, Atmo needs to be able to connect to external resources. Currently, Atmo can connect to [NATS](https://nats.io/), [Redis](https://redis.io/), [Kafka](https://kafka.apache.org/), [MySQL](https://www.mysql.com/), and [PostgreSQL](https://www.postgresql.org/). Upcoming releases will include additional data sources as well.

website/docs/atmo/usage/connections.md

@@ -1,3 +1,7 @@
+---
+pagination_prev: null
+---
+
 # Creating Runnables
 
 :::note

website/docs/atmo/usage/creating-runnables.md

@@ -3,13 +3,15 @@ pagination_prev: null
 ---
 # Suborbital Compute
 
-### The SaaS extensibility platform
+![Suborbital logo](/img/suborbital-logo-wide.svg)
 
-![](/img/suborbital-logo-wide.svg)
+Suborbital Compute is a platform that allows your users to write and deploy 
+functions and workflows that integrate into your app. Our WebAssembly-based 
+compute 
+core lets you run user code within your infrastructure while being sure you're protected from malicious code.
 
-Suborbital Compute is a platform that allows your users to write and deploy serverless extensions for your app so they can develop custom integrations, customizations, and workflows. Our WebAssembly-based compute core lets you run user code within your infrastructure while being sure that you're protected from malicious code.
-
-Compute is now in public beta! We are excited for you to [give it a try](https://suborbital.network) and send us your feedback.
+Compute is now in public beta! We are excited for you to [give it a try](/get-started)
+and send us your feedback. 
 
 Compute gives you everything you need to run your users' functions in a secure sandbox and integrate them into your product in whatever way makes sense for you. This includes a code editor, builder service, and an easy-to-use API.
 

website/docs/compute/api-reference/api-reference.md

@@ -0,0 +1,63 @@
+---
+pagination_prev: null
+---
+
+# Function editor
+
+The Compute code editor is available for you to embed in your application, so your users can build their functions quickly and easily:
+
+![Compute editor containing a 'Hello' function](../../assets/editor-screen.png)
+
+The editor is hosted at `https://editor.suborbital.network`, and uses URL parameters to configure its connection to your builder service.
+
+You will host the Compute builder service in your cloud infrastructure with a configured DNS name. An HTTPS connection to the builder is required to use the editor.
+
+To launch the editor, you can either [embed the editor in a frame]
+(https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe) within your own webpage, or launch it in a new tab.
+
+## Editor token
+
+To authenticate the editor for a specific user to edit their own functions,[Compute's Administrative API provides an API to create an `editor token` ]
+(https://suborbital-compute.readme.io/reference/gettoken) for a given function.
+
+## Configuration
+
+The editor is configured with URL parameters. Here's an example:
+
+`https://editor.suborbital.network?builder=https://builder.acmeco.com&token=K78as0aslwi30l8h5lbF4lS7&ident=com.suborbital.customer&fn=add-record`
+
+Let's break it down:
+
+**Builder**: `?builder=https://builder.acmeco.com`
+
+* This is the URL of your public builder service
+
+**Token**: `&token=K78as0aslwi30l8h5lbF4lS7`
+
+* The editor token retrieved from the control-plane service
+
+**Ident**: `&ident=com.suborbital.customer`
+
+* The identifier used when addressing your specific user, see  [Fully-qualified function names](./fully-qualified-function-names.md) for more details
+
+**Fn**: `&fn=add-record`
+
+* The specific function name that the editor should load
+
+**Namespace** (optional): `&namespace=default`
+
+* The function namespace (if not included, the `default` namespace is used, see [Namespaces](docs/compute/customizing-functions/namespaces.md) for more details)
+
+**Template** (optional): `&template=assemblyscript`
+
+* The language template used for new functions. Check out our [supported  languages](../../reactr/language-support.md)!
+
+If the `fn` in question does not exist, the editor will automatically create a new function.
+
+## Building and deploying
+
+Once the user has edited their function, the `build` button in the top right will allow them to check to ensure the function builds. The builder service will build the function and then return the results to the console area.
+
+Assuming the build succeeds, the user can choose to deploy the latest version with the `deploy` button. If they choose not to deploy, the draft will be available to them later.
+
+Until the user deploys the function, it will remain at the previous version. The [API Reference](https://suborbital-compute.readme.io/reference/api-reference) gives you details about the draft and active versions of any function.

website/docs/compute/building-functions/github-integration.md

@@ -12,7 +12,7 @@ To create a custom function template, create a fork of the `runnable-templates`
 
 Once the repo has been forked into your company or personal account, you can begin editing the `templates` directory to fit your needs.
 
-For now, you are limited to one template per language, but in the future you will be able to create a set of templates for your users to choose from.
+For now, you are limited to one template per language, but in the future you'll be able to create a set of templates for your users to choose from.
 
 ### AssemblyScript
 

website/docs/compute/compute.md

@@ -1,24 +1,30 @@
+---
+pagination_next: null
+---
+
 # Fully-qualified function names
 
 Each function uploaded by your users has a unique name called a fully-qualified function name, or FQFN. The string representation of an FQFN is as follows:
 
 ```bash
-com.awesomeco.nawronuq98hqwekj198fkljbeco#default::[email protected]
-|____________|___________________________|________|____________|______|
+com.example.nawronuq98hqwekj198fkljbeco#default::[email protected]
+|_____________|___________________________|________|____________|______|
  Environment          User ID             Namespace  Function   Version
 ```
 
 Here's a breakdown:
 
-* **Environment**: your company's reverse domain; `com.awesomeco`
+* **Environment**: your company's reverse domain; `com.example`
 * **User ID**: The unique value that your application uses to identify your users within your system; `nawronuq98hqwekj198fkljbeco`
-* **Namespace**: The namespace this function belongs to; allows for separated groups of functions based on product needs \(see [Namespaces](namespaces.md) \); `default`
+* **Namespace**: The namespace this function belongs to; allows for separated groups of functions based on product needs (see [Namespaces](docs/compute/customizing-functions/namespaces.md) ); `default`
 * **Function**:  The name of the function as chosen by the user; `record-event`
 * **Version**: The version of this function \(incremented each time a user updates this function\); `v1.0.0`
 
 ## Environment name
 
-The domain of your email address should match the `environment` you configure for Compute, i.e. if your email is `[email protected]`, your Compute environment would be called `com.awesomeco`.
+The domain of your email address should match the `environment` you 
+configure for Compute, i.e. if your email is `[email protected]`, your 
+Compute environment would be called `com.example`.
 
 ## FQFN URLs
 
@@ -28,7 +34,7 @@ To execute a function in Compute you will use a URL representation of FQFN. To r
 /{environment}.{userid}/{namespace}/{function}/{version}
 
 Example:
-/com.awesomeco.nawronuq98hqwekj198fkljbeco/default/record-event/v1.0.0
+com.example.nawronuq98hqwekj198fkljbeco/default/record-event/v1.0.0
 ```
 
 

website/docs/compute/concepts/data-plane-vs-control-plane.md

@@ -1,3 +1,7 @@
+---
+pagination_next: null
+---
+
 # Namespaces
 
 Within Compute, your users' functions can be organized into `namespaces` at your discretion \(you control them, not your users\). Namespaces can be used to organize groups of functions designed for different use-cases within your product.

website/docs/compute/customizing-functions/code-editor.md

@@ -1,8 +1,12 @@
+---
+pagination_prev: null
+---
+
 # Configure capabilities
 
 Compute functions can access a number of capabilities:
 
-* Logger
+* Logging
 * HTTP requests
 * GraphQL requests
 * Key/value store (cache)

website/docs/compute/customizing-functions/custom-function-templates.md

@@ -1,4 +1,4 @@
-# Configure Storage
+# Configure storage
 
 By default, Compute will store compiled functions and function source code on the local storage in your Kubernetes cluster. For greater scalability, Compute can be configured to store artifacts in cloud-based object storage like Amazon S3 or Google Cloud Storage.
 

website/docs/compute/concepts/fully-qualified-function-names.md website/docs/compute/customizing-functions/fully-qualified-function-names.md

@@ -1,4 +1,4 @@
-# Configure Webhooks
+# Configure webhooks
 
 Certain actions in Compute can trigger webhooks to notify other services of the event. The receivers of webhooks get contextually relevant information about the request Compute receiver. By default, no webhooks are configured.
 
@@ -7,7 +7,7 @@ You can set your own webhooks in the `scc-config.yaml` file that `subo` created
 ## Configuration options
 The `webhooks` stanza in `scc-config.yaml` consists of a top level `webhooks` object with a list of entries.
 
-Each entry has an `id` referencing one of the predefined [hook points](#hook-points) and a list of **one or more** HTTP `targets`, which consist of a `url`, `method`, and dictionary of `headers` (optional).
+Each entry has an `id` referencing the `builder.function.promoted` hook point and a list of **one or more** HTTP `targets`, which consist of a `url`, `method`, and dictionary of `headers` (optional).
 
 ## Examples
 
@@ -41,12 +41,19 @@ webhooks:
        method: POST
        headers: *commonHeaders
 ```
-
 ## Hook points
-### `builder.function.promoted`
-**Description**: Runs when an end user successfully deploys a function.
 
-**Sample response** (JSON):
+:::info Devs at work
+Stay tuned for more hook points!
+:::
+
+
+ `builder.function.promoted`
+ 
+**Description** Runs when an end user successfully deploys a function. 
+
+**Sample response(JSON):**
+
 ```json
 {
     "webhook_id": "builder.function.promoted",

website/docs/compute/concepts/namespaces.md website/docs/compute/customizing-functions/namespaces.md

@@ -1,20 +1,26 @@
+---
+pagination_next: null
+---
+
 # Deploy Compute to your cloud environment
 
-To install Compute in the cloud, you'll use the `subo` tool to automatically install the Suborbital Compute Core into a Kubernetes cluster. You need to ensure you have some **pre-requisites** ready:
+To install Compute in the cloud, you'll use the `subo` tool to 
+automatically install Suborbital Compute into a Kubernetes cluster. 
+You need to ensure you have some **pre-requisites** ready:
 
 1. Deploy a Kubernetes cluster into your cloud provider of choice (if you have a pre-existing one, that works too!).
-   * [Ensure there is a storage class available in Kubernetes]
-   * (https://kubernetes.io/docs/concepts/storage/storage-classes/). Some cloud providers such as AWS do not have a default storage class. See this great [GitLab guide on how to set up a storage class](https://docs.gitlab.com/charts/installation/storage.html#configuring-cluster-storage).
-   * If you would like assistance with storage, [send us an email](mailto:[email protected])!
+   * [Ensure there is a storage class available in Kubernetes](https://kubernetes.io/docs/concepts/storage/storage-classes/). Some cloud providers such as AWS do not have a default storage class. See this great [GitLab guide on how to set up a storage class](https://docs.gitlab.com/charts/installation/storage.html#configuring-cluster-storage).
+   * If you would like assistance with storage, [send us an email](mailto:[email protected]) or hit us up on [Discord](https://chat.suborbital.dev)!
 2. [Install the `kubectl` tool](https://kubernetes.io/docs/tasks/tools/#kubectl) and authenticate it with the cluster you want to use.
 3. Ensure you have access to modify your company's DNS records, as you need to create a domain name for the builder service (it must run on HTTPS, which requires a domain)
-4. Ensure you've run the `subo compute create token <email>` command from [Create an environment token](../quickstart/1.-create-an-environment-token-with-subo.md) before attempting the install
+4. Ensure you've run the [`subo compute create token <email>` command](../get-started#generate-your-token.md) before attempting the install
 
 :::info
 `subo` creates a `suborbital` Kubernetes namespace and installs the `KEDA` autoscaler. Don't worry about existing applications installed in the cluster; this won't affect them!
 :::
 
-Once you have the pre-requisites in place, navigate to the `suborbital` directory you created in the [quickstart guide](../quickstart/1.-create-an-environment-token-with-subo.md) and use `subo` to install:
+Once you have the pre-requisites in place, navigate to the `suborbital` 
+directory you created when you [generated your token](../get-started#generate-your-token.md) and use `subo` to install:
 
 ```bash
 subo compute deploy core
@@ -31,7 +37,7 @@ kubectl get svc -n suborbital
 
 ## Set up DNS
 
-When you deploy, a `LoadBalancer` is created for the builder called `scc-builder-service`. You should wait until an external IP address is provisioned for the service (use the `get svc` command above to check), and then create a DNS `A` record that matches the domain name you entered during setup. This will allow the builder to automatically provision a TLS certificate and connect with the [code editor](../integrate-the-function-editor/code-editor.md) securely.
+When you deploy, a `LoadBalancer` is created for the builder called `scc-builder-service`. You should wait until an external IP address is provisioned for the service (use the `get svc` command above to check), and then create a DNS `A` record that matches the domain name you entered during setup. This will allow the builder to automatically provision a TLS certificate and connect with the [code editor](docs/compute/customizing-functions/code-editor.md) securely.
 
 ## What's next