GitBook: [main] 4 pages modified

docs/README.md

@@ -1,21 +1,20 @@
-## Welcome
+# Welcome
 
-Building web services should be simple. Atmo makes it easy to create a powerful server application wihout needing to worry about scalability, infrastructure, or complex networking.
+Building web services should be simple. Atmo makes it easy to create a powerful server application without needing to worry about scalability, infrastructure, or complex networking.
 
-Atmo enables you to write small self-contained functions called Runnables using a variety of laguages, and define your business logic by declaritvely composing them. Atmo then automatically scales out a flat network of instances to handle traffic using its meshed message bus and embedded job scheduler. Atmo can handle request-based traffic, and soon will be able to handle events sourced from various systems like Kafka or EventBridge.
+Atmo enables you to write small self-contained functions called Runnables using a variety of languages, and define your business logic by declaritvely composing them. Atmo then automatically scales out a flat network of instances to handle traffic using its meshed message bus and embedded job scheduler. Atmo can handle request-based traffic, and soon will be able to handle events sourced from various systems like Kafka or EventBridge.
 
-The Atmo Directive is a YAML file wherein you declare your application's behaviour. Because the Directive can describe everything you need to make your application work (including routes, logic, and more), there is no need to write boilerplate ever again.
+The Atmo Directive is a YAML file wherein you declare your application's behaviour. Because the Directive can describe everything you need to make your application work \(including routes, logic, and more\), there is no need to write boilerplate ever again.
 
 Atmo is not a library, but rather a self-hosted platform that uses a bundle containing your Runnables and Directive to automatically run your application.
 
-With Atmo, you only need to do three things:
-1. Write self-contained, composable functions
-2. Declare how you want Atmo to handle requests by creating a "Directive"
-3. Build and deploy your Runnable bundle
+With Atmo, you only need to do three things: 1. Write self-contained, composable functions 2. Declare how you want Atmo to handle requests by creating a "Directive" 3. Build and deploy your Runnable bundle.
 
 ## Status
-Atmo is currently in **alpha**, and is intended to be the flagship project in the Suborbital Development Platform. 
+
+Atmo is currently in **alpha**, and is intended to be the flagship project in the Suborbital Development Platform.
 
 Atmo is built atop [Vektor](https://github.com/suborbital/vektor), [Hive](https://github.com/suborbital/hive) and [Grav](https://github.com/suborbital/grav).
 
-Copyright Suborbital contributors 2020.
+Copyright Suborbital contributors 2020.
+

docs/SUMMARY.md

@@ -5,4 +5,5 @@
 
 ## Introduction
 
-* [Get Started](introduction/getstarted/README.md)
+* [Get Started](introduction/getstarted.md)
+

docs/background.md

@@ -2,4 +2,5 @@
 
 Atmo was born out of a desire to simplify backend development by making it easy to bootstrap new projects, automatically scale to handle large amounts of traffic, and ensure their security with new technology and best practices. Atmo embodies the [SUFA design pattern](https://blog.suborbital.dev/how-to-familiarize-yourself-with-a-new-codebase) by making it easy to develop, deploy, and scale your application. To develop applications using Atmo, a declarative file called the Directive is used to describe how to handle requests and events using composable functions. This allows the developer to describe the entirety of their application's behaviour, while only needing to write code for the functions being called. Atmo then uses the Directive to run the desired application, automatically running a webserver, job scheduler, and messaging mesh together to form a powerful platform upon which your application can thrive.
 
-The core of Atmo is a job scheduler running WebAssembly modules, which allows running functions written in a variety of languages at near-native speed with massive improvements to security and orchestration. Atmo scales out using capability groups, which allows groups of Atmo instances to access sensitive resources, scale independently, and ensure your application is able to grow efficiently to handle increases in traffic with ease. Atmo's built in meshing capabilities means that building a flat network of instances is automated, secure, and efficient. Atmo strives to make everything about developing and deploying your application simple so that you can focus on the hard problems of building your product. Atmo's mission statement is "help developers build applications that are powerful but never complicated".
+The core of Atmo is a job scheduler running WebAssembly modules, which allows running functions written in a variety of languages at near-native speed with massive improvements to security and orchestration. Atmo scales out using capability groups, which allows groups of Atmo instances to access sensitive resources, scale independently, and ensure your application is able to grow efficiently to handle increases in traffic with ease. Atmo's built in meshing capabilities means that building a flat network of instances is automated, secure, and efficient. Atmo strives to make everything about developing and deploying your application simple so that you can focus on the hard problems of building your product. Atmo's mission statement is "help developers build applications that are powerful but never complicated".
+

docs/introduction/getstarted.md

@@ -0,0 +1,69 @@
+# Get Started
+
+**NOTE:** These docs are far from complete, but are being actively worked on.
+
+Atmo is a self-hosted platform that uses a _Runnable bundle_ to run your described application. The bundle includes two things: a Directive, and a set of Runnables \(WebAssembly modules compiled from various languages such as Rust and Swift\).
+
+## Building a bundle
+
+Bundles are built using `subo`, which is the Suborbital CLI tool. You'll need to install `subo` to build a bundle. To install the tool, [visit the subo repository](https://github.com/suborbital/subo).
+
+Once you've installed `subo`, you can use it to build the example project included with [the Atmo repository](https://github.com/suborbital/atmo). To get started, run:
+
+```bash
+git clone git@github.com:suborbital/atmo.git
+cd atmo
+subo build ./example-project --bundle
+```
+
+The end of this command should read `✅ DONE: bundle was created -> example-project/runnables.wasm.zip`
+
+## Running Atmo
+
+Once you have your Runnable bundle, you can run Atmo:
+
+```text
+> ATMO_HTTP_PORT=8080 make atmo bundle=./example-project/runnables.wasm.zip
+```
+
+Atmo will start up and you will begin to see its structured logs in your terminal. Make a request to `POST localhost:8080/hello` with a request body of `https://github.com`. You will receive HTML fetched from `https://github.com/suborbital`.
+
+## Using Docker
+
+If you prefer using Docker, you can locally build and run Atmo in Docker using:
+
+```text
+> make atmo/docker dir=example-project
+```
+
+## How it works
+
+If you explore the `example-project` directory, you will see several Runnables \(`fetch-test`, `modify-url`, etc.\) and a `Directive.yaml` file. Each folder represents an Atmo function, and the Directive is responsible for describing how those functions should be used. The Directive looks like this:
+
+```yaml
+identifier: com.suborbital.test
+version: v0.0.1
+
+handlers:
+  - type: request
+    resource: /hello
+    method: POST
+    steps:
+      - group:
+        - modify-url
+        - helloworld-rs
+      - fn: fetch-test
+```
+
+This describes the application being constructed. This declares a route \(`POST /hello`\) and how to handle that request. The `steps` provided contain a set of instructions for how to handle requests to the `/hello` endpoint. 
+
+The first step is a `group`, meaning that all of the functions in that group will be executed **concurrently**. 
+
+The second step is a single function that uses the [Runnable API](https://github.com/suborbital/hive-wasm) to make an HTTP request. The API is continually evolving to include more capabilities. In addition to making HTTP requests, it includes logging abilities and more.
+
+For each function executed, its result gets stored in the request handler's `state`. The `state` is used to pass values between functions, since they are completely isolated and independent from one another. The `modify-url` function takes the request body and modifies it \(in this case, adding `/suborbital` to it\). The second step \(`fetch-test`\) takes that modified URL and makes an HTTP request to fetch it. The final function's output is used as the response data for the request.
+
+## Coming soon
+
+Further functionality is incoming along with improved docs, more examples, and an improved Directive format. Visit [the Suborbital website](https://suborbital.dev) to sign up for email updates related to new versions of Atmo.
+