stub out docs

docs/README.md

@@ -0,0 +1 @@
+getting-started/introduction.md

docs/configuration/agents.md

@@ -1,6 +1,6 @@
 # Agents
 
-Agents are specialized [Services](../reference/app/primitives/service.md) that run a single
+Agents are specialized [Services](../reference/primitives/app/service.md) that run a single
 [Process](../reference/app/primitives/process.md) on each [Instance](../reference/app/primitives/instance.md).
 
 ## Configuration

docs/configuration/convox.yml.md

@@ -0,0 +1,5 @@
+---
+order: 1
+---
+
+# convox.yml

docs/configuration/environment.md

@@ -0,0 +1,94 @@
+# Environment Variables
+
+Convox encourages the use of environment variables for managing application secrets. Using environment
+variables allows you to keep secrets out of your codebase and to have different configuration values
+for different deployments (i.e. staging and production).
+
+## Definition
+
+Environment variables that will be used by the application are defined in `convox.yml`:
+
+### Application Level
+
+Environment variables defined at the top level affect every service in the application.
+
+    environment:
+      - ENCRYPTION_KEY
+    services:
+      web:
+        environment:
+          - ALLOWED_IPS
+          - COOKIE_SECRET
+      worker:
+        environment:
+          - QUEUE
+
+This application would require four environment variables to be set: `ALLOWED_IPS`, `COOKIE_SECRET`, `ENCRYPTION_KEY`, and `QUEUE`.
+
+The `ENCRYPTION_KEY` variable will be available to both services.
+
+### Service Level
+
+Environment variables can be defined for each [Service](../reference/app/primitives/service.md).
+
+    services:
+      web:
+        environment:
+          - ALLOWED_IPS
+          - COOKIE_SECRET
+      worker:
+        environment:
+          - QUEUE
+
+This application would require three environment variables to be set: `ALLOWED_IPS`, `COOKIE_SECRET`, and `QUEUE`.
+
+> Environment variables defined at the service level will only be available to that service. In the example above,
+> the `web` service would not have a value set for the `QUEUE` environment variable as that variable is only defined
+> on the `worker` service.
+
+
+### Default Values
+
+You can set a default value for any environment variable in the manifest:
+
+    environment:
+      - QUEUE=main
+
+### Interpolation
+
+You can also use environment variables to add dynamic configuration to your `convox.yml`:
+
+    services:
+      web:
+        health: ${HEALTH_CHECK_PATH}
+
+## Configuration
+
+You can set values for your environment variables using `convox env set`:
+
+    $ convox env set ALLOWED_IPS=1.2.3.4 COOKIE_SECRET=foo QUEUE=main
+    Setting ALLOWED_IPS, COOKIE_SECRET, QUEUE... OK
+    Release: RABCDEFGHI
+
+Setting environment variables will cause a new [Release](../reference/app/primitives/release.md) to be created. In order to deploy
+your changes you will need to promote this release.
+
+    $ convox releases promote RABCDEFGHI
+    Promoting RABCDEFGHI... OK
+
+> Environment variables must be defined in the `convox.yml` for their values to be populated on a
+> [Service](../reference/app/primitives/service.md).
+
+## System Variables
+
+The following environment variables are automatically set by Convox.
+
+| Name                | Description                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------------- |
+| `APP`               | Name of the [App](../reference/app.md)                                                        |
+| `BUILD`             | ID of the currently-promoted [Build](../reference/app/primitives/build.md)                    |
+| `BUILD_DESCRIPTION` | Description of the currently-promoted [Build](../reference/app/primitives/build.md)           |
+| `PORT`              | The value of the `port:` attribute for this [Service](../reference/app/primitives/service.md) |
+| `RACK`              | The name of the [Rack](../reference/rack.md)                                                  |
+| `RELEASE`           | ID of the currently-promoted [Release](../reference/app/primitives/release.md)                |
+| `SERVICE`           | Name of the [Service](../reference/app/primitives/service.md)                                 |

docs/development/local-development.md

@@ -0,0 +1,5 @@
+---
+order: 1
+---
+
+# Local Development

docs/getting-started/introduction.md

@@ -0,0 +1,5 @@
+---
+order: 1
+---
+
+# Introduction

docs/installation/cli.md

@@ -1,4 +1,4 @@
-# CLI Installation
+# Command Line Interface
 
 ## Linux
 
@@ -10,4 +10,4 @@
 
     $ curl -L https://github.com/convox/convox/releases/latest/download/convox-macos -o /tmp/convox
     $ sudo mv /tmp/convox /usr/local/bin/convox
-    $ sudo chmod 755 /usr/local/bin/convox
+    $ sudo chmod 755 /usr/local/bin/convox

docs/installation/development-rack.md

@@ -0,0 +1,71 @@
+# Development Rack
+
+## Install Kubernetes
+
+### MacOS
+
+- Install [Docker Desktop](https://www.docker.com/products/docker-desktop)
+- Go to Docker Desktop Preferences
+- Go to the Advanced tab
+- Drag the CPU slider to the halfway point
+- Drag the Memory slider to at least 8GB
+- Go to the Kubernetes tab
+- Enable Kubernetes
+
+### Ubuntu
+
+- `snap install microk8s --classic --channel=1.13/stable`
+- `microk8s.enable dns storage`
+- `mkdir -p ~/.kube`
+- `microk8s.config > ~/.kube/config`
+- `sudo snap restart microk8s`
+
+## Install Convox
+
+- Create a new directory, e.g. `~/racks/development`
+- Switch to this directory
+- Create a file named `main.tf` with the following contents:
+
+```
+module "system" {
+  source = "github.com/convox/convox//terraform/system/local"
+  name   = "development"
+}
+```
+
+- Run `terraform init`
+- Run `terraform apply`
+
+## DNS Setup
+
+Set `*.convox` to be resolved by the local Rack's DNS server.
+
+### MacOS
+
+- `sudo mkdir -p /etc/resolver`
+- `sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/convox'`
+
+### Ubuntu
+
+- `sudo mkdir -p /usr/lib/systemd/resolved.conf.d`
+- `sudo bash -c "printf '[Resolve]\nDNS=$(kubectl get service/resolver-external -n convox-system -o jsonpath="{.spec.clusterIP}")\nDomains=~convox' > /usr/lib/systemd/resolved.conf.d/convox.conf"`
+- `systemctl daemon-reload`
+- `systemctl restart systemd-networkd systemd-resolved`
+
+## CA Trust (optional)
+
+To remove browser warnings about untrusted certificates for local applications
+you can trust the Rack's CA certificate.
+
+This certificate is generated on your local machine and is unique to your Rack.
+
+### MacOS
+
+- `kubectl get secret/ca -n convox-system -o jsonpath="{.data.tls\.crt}" | base64 -d > /tmp/ca`
+- `sudo security add-trusted-cert -d -r trustRoot -k /Library/Keychains/System.keychain /tmp/ca`
+
+### Ubuntu
+
+- `kubectl get secret/ca -n convox-system -o jsonpath="{.data.tls\.crt}" | base64 -d > /tmp/ca`
+- `sudo mv /tmp/ca /usr/local/share/ca-certificates/convox.crt`
+- `sudo update-ca-certificates`

docs/installation/production-rack/README.md

@@ -0,0 +1 @@
+# Production Rack

docs/installation/production-rack/aws.md

@@ -0,0 +1 @@
+# Amazon Web Services

docs/installation/production-rack/azure.md

@@ -0,0 +1 @@
+# Microsoft Azure

docs/installation/production-rack/do.md

@@ -0,0 +1 @@
+# Digital Ocean

docs/installation/production-rack/gcp.md

@@ -0,0 +1 @@
+# Google Cloud

docs/integrations/ci/README.md

@@ -0,0 +1 @@
+# Continuous Integration

docs/integrations/ci/circleci.md

@@ -0,0 +1 @@
+# CircleCI

docs/integrations/logging/logdna.md

@@ -0,0 +1 @@
+# LogDNA

docs/reference/app/primitives.md

@@ -1,35 +0,0 @@
-# Primitives
-
-Primitives are the basic building blocks of an [App](../app.md).
-
-Primitives are defined in [`convox.yml`](convox.yml.md) and can be easily composed to provide
-useful functionality that lets you focus on the bits that make your [App](../app.md) unique.
-
-## Available Primitives
-
-| Primitive                          | Description                                                                                         |
-| :--------------------------------- | :-------------------------------------------------------------------------------------------------- |
-| [Balancer](primitives/balancer.md) | Custom TCP load balancers in front of a [Service](primitives/service.md)                            |
-| [Build](primitives/build.md)       | Compiled version of a codebase                                                                      |
-| [Object](primitives/object.md)     | Blob/file storage                                                                                   |
-| [Process](primitives/process.md)   | Running containers created by running a command on a [Release](primitives/build.md)                 |
-| [Release](primitives/release.md)   | Units of deployment consisting of a [Build](primitives/build.md) and a set of environment variables |
-| [Resource](primitives/resource.md) | Network-accessible external services (e.g. Postgres)                                                |
-| [Service](primitives/service.md)   | Horizontally-scalable collections of durable [Processes](primitives/process.md)                     |
-| [Timer](primitives/timer.md)       | Runs one-off [Processes](primitives/process.md) on a scheduled interval                             |
-
-## Planned Primitives
-
-| Primitive | Description                                 |
-| :-------- | :------------------------------------------ |
-| Cache     | Store data with timed expiration            |
-| Feature   | Toggleable feature flags                    |
-| Identity  | User, group, and permission management      |
-| Key       | Encrypt and decrypt data                    |
-| Lock      | Coordinate exclusive access                 |
-| Mail      | Send and receive email                      |
-| Metric    | Store and analyze time-series data          |
-| Queue     | An expandable list of items to be processed |
-| Search    | Full-text indexing of data                  |
-| Stream    | Subscribable one-to-many data stream        |
-| Table     | Indexable rows of key/value data            |

docs/reference/cli/README.md

@@ -0,0 +1 @@
+# CLI Commands

docs/reference/cli/api.md

@@ -0,0 +1,23 @@
+# api
+
+## api get
+
+Query the Rack API
+
+### Usage
+
+    convox api get <path>
+
+### Examples
+
+    $ convox api get /apps
+    [
+      {
+        "generation": "3",
+        "locked": false,
+        "name": "myapp",
+        "release": "RABCDEFGHI",
+        "router", "0a1b2c3d4e5f.convox.cloud",
+        "status": "running"
+      }
+    ]

docs/reference/primitives/README.md

@@ -0,0 +1,42 @@
+# Primitives
+
+Primitives are the building blocks available to build an [App](app) on Convox.
+
+Primitives can be easily composed to provide useful functionality that lets you
+focus on the things that make your [App](../app.md) unique.
+
+## App Primitives
+
+| Primitive                   | Description                                                                                  |
+|:----------------------------|:---------------------------------------------------------------------------------------------|
+| [Balancer](app/balancer.md) | Custom TCP load balancers in front of a [Service](app/service.md)                            |
+| [Build](app/build.md)       | Compiled version of a codebase                                                               |
+| [Object](app/object.md)     | Blob/file storage                                                                            |
+| [Process](app/process.md)   | Running containers created by running a command on a [Release](app/build.md)                 |
+| [Release](app/release.md)   | Units of deployment consisting of a [Build](app/build.md) and a set of environment variables |
+| [Resource](app/resource.md) | Network-accessible external services (e.g. Postgres)                                         |
+| [Service](app/service.md)   | Horizontally-scalable collections of durable [Processes](app/process.md)                     |
+| [Timer](app/timer.md)       | Runs one-off [Processes](app/process.md) on a scheduled interval                             |
+
+### Coming Soon
+
+| Primitive | Description                                 |
+|:----------|:--------------------------------------------|
+| Cache     | Store data with timed expiration            |
+| Feature   | Toggleable feature flags                    |
+| Identity  | User, group, and permission management      |
+| Key       | Encrypt and decrypt data                    |
+| Lock      | Coordinate exclusive access                 |
+| Mail      | Send and receive email                      |
+| Metric    | Store and analyze time-series data          |
+| Queue     | An expandable list of items to be processed |
+| Search    | Full-text indexing of data                  |
+| Stream    | Subscribable one-to-many data stream        |
+| Table     | Indexable rows of key/value data            |
+
+## Rack Primitives
+
+| Primitive                    | Description                                                         |
+|:-----------------------------|:--------------------------------------------------------------------|
+| [Instance](rack/instance.md) | Node that provides capacity for running [Processes](app/process.md) |
+| [Registry](rack/registry.md) | External image repository                                           |

docs/reference/primitives/app/service.md

@@ -10,47 +10,52 @@ Services can be scaled to a static count or autoscaled in a range based on metri
 
 A Service is defined in [`convox.yml`](../convox.yml.md).
 
-    services:
-      web:
-        port: 5000
+```
+services:
+  web:
+    build: .
+    health: /check
+    port: 5000
+    scale: 3
+```
 
----
-
-    services:
-      web:
-        agent: false
-        build: .
-        command: bin/web
-        domain: ${WEB_HOST}
-        drain: 10
-        environment:
-          - FOO
-          - BAR=qux
-        health:
-          grace: 10
-          interval: 5
-          path: /check
-          timeout: 3
-        internal: false
-        port: 5000
-        ports:
-          - 5001
-          - 5002
-        privileged: false
-        scale:
-          count: 1-3
-          cpu: 128
-          memory: 512
-          targets:
-            cpu: 50
-            memory: 80
-        singleton: false
-        sticky: true
-        test: make test
-        volumes:
-          - /shared
-
-### Attributes
+```
+services:
+  web:
+    agent: false
+    build:
+      manifest: Dockerfile
+      path: .
+    command: bin/web
+    domain: ${WEB_HOST}
+    drain: 10
+    environment:
+      - FOO
+      - BAR=qux
+    health:
+      grace: 10
+      interval: 5
+      path: /check
+      timeout: 3
+    internal: false
+    port: 5000
+    ports:
+      - 5001
+      - 5002
+    privileged: false
+    scale:
+      count: 1-3
+      cpu: 128
+      memory: 512
+      targets:
+        cpu: 50
+        memory: 80
+    singleton: false
+    sticky: true
+    test: make test
+    volumes:
+      - /shared
+```
 
 | Attribute     | Type       | Default             | Description                                                                                                                         |
 | ------------- | ---------- | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
@@ -66,7 +71,7 @@ A Service is defined in [`convox.yml`](../convox.yml.md).
 | `port`        | string     |                     | The port that the default Rack balancer will use to [route incoming traffic](../../../guides/load-balancing.md)                     |
 | `ports`       | list       |                     | A list of ports available for internal [service discovery](../../../guides/service-discovery.md) or custom [Balancers](balancer.md) |
 | `privileged`  | boolean    | true                | Set to `false` to prevent [Processes](process.md) of this Service from running as root inside their container                       |
-| `scale`       | map        | 1                   | Horizontal scaling definition (see below)                                                                                           |
+| `scale`       | map        | 1                   | Define scaling parameters (see below)                                                                                               |
 | `singleton`   | boolean    | false               | Set to `true` to prevent extra [Processes](process.md) of this Service from being started during deployments                        |
 | `sticky`      | boolean    | false               | Set to `true` to enable [sticky sessions](../../../guides/sticky-sessions.md)                                                       |
 | `test`        | string     |                     | A command to run to test this Service when running `convox test`                                                                    |
@@ -74,18 +79,16 @@ A Service is defined in [`convox.yml`](../convox.yml.md).
 
 > Environment variables **must** be declared to be populated for a Service.
 
-#### build
-
-Specifying `build` as a string will set the `path` and leave the other values as defaults.
+### build
 
 | Attribute  | Type   | Default    | Description                                                   |
 | ---------- | ------ | ---------- | ------------------------------------------------------------- |
 | `manifest` | string | Dockerfile | The filename of the Dockerfile                                |
 | `path`     | string | .          | The path (relative to `convox.yml`) to build for this Service |
 
-#### health
+> Specifying `build` as a string will set the `path` and leave the other values as defaults.
 
-Specifying `health` as a string will set the `path` and leave the other values as defaults.
+### health
 
 | Attribute  | Type   | Default | Description                                                                                      |
 | ---------- | ------ | ------- | ------------------------------------------------------------------------------------------------ |
@@ -94,9 +97,9 @@ Specifying `health` as a string will set the `path` and leave the other values a
 | `path`     | string | /       | The path to request for health checks                                                            |
 | `timeout`  | number | 4       | The number of seconds to wait for a successful response                                          |
 
-#### scale
+> Specifying `health` as a string will set the `path` and leave the other values as defaults.
 
-Specifying `scale` as a number will set the `count` and leave the other values as defaults.
+### scale
 
 | Attribute | Type   | Default | Description                                                                                                   |
 | --------- | ------ | ------- | ------------------------------------------------------------------------------------------------------------- |
@@ -105,7 +108,9 @@ Specifying `scale` as a number will set the `count` and leave the other values a
 | `memory`  | number | 256     | The number of MB of RAM to reserve for [Processes](process.md) of this Service                                |
 | `targets` | map    |         | Target metrics to trigger autoscaling                                                                         |
 
-#### scale.targets
+> Specifying `scale` as a number will set the `count` and leave the other values as defaults.
+
+### scale.targets
 
 | Attribute | Type   | Default | Description                                                                                |
 | --------- | ------ | ------- | ------------------------------------------------------------------------------------------ |
@@ -123,7 +128,7 @@ Specifying `scale` as a number will set the `count` and leave the other values a
 
 ### Scaling a Service
 
-    $ convox scale web --count 3 --cpu 256 --memory 1024 -a myapp
+    $ convox scale web --count 3 --cpu 256 --memory 1024 -a myapp`1
     Scaling web... OK
 
 ### Restarting a Service

docs/tutorials/deploying-an-application.md

@@ -0,0 +1 @@
+# Deploying an Application