diff --git a/docs/README.md b/docs/README.md new file mode 120000 index 0000000..b3e7dc3 --- /dev/null +++ b/docs/README.md @@ -0,0 +1 @@ +getting-started/introduction.md \ No newline at end of file diff --git a/docs/guides/agents.md b/docs/configuration/agents.md similarity index 94% rename from docs/guides/agents.md rename to docs/configuration/agents.md index acc2174..f51f9f4 100644 --- a/docs/guides/agents.md +++ b/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 diff --git a/docs/configuration/convox.yml.md b/docs/configuration/convox.yml.md new file mode 100644 index 0000000..1f02528 --- /dev/null +++ b/docs/configuration/convox.yml.md @@ -0,0 +1,5 @@ +--- +order: 1 +--- + +# convox.yml diff --git a/docs/reference/app/convox.yml.md b/docs/configuration/dockerfile.md similarity index 100% rename from docs/reference/app/convox.yml.md rename to docs/configuration/dockerfile.md diff --git a/docs/configuration/environment.md b/docs/configuration/environment.md new file mode 100644 index 0000000..5c4c148 --- /dev/null +++ b/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) | diff --git a/docs/reference/rack.md b/docs/configuration/health-checks.md similarity index 100% rename from docs/reference/rack.md rename to docs/configuration/health-checks.md diff --git a/docs/guides/load-balancing.md b/docs/configuration/load-balancing.md similarity index 100% rename from docs/guides/load-balancing.md rename to docs/configuration/load-balancing.md diff --git a/docs/reference/rack/instance.md b/docs/configuration/persistent-storage.md similarity index 100% rename from docs/reference/rack/instance.md rename to docs/configuration/persistent-storage.md diff --git a/docs/guides/service-discovery.md b/docs/configuration/service-discovery.md similarity index 100% rename from docs/guides/service-discovery.md rename to docs/configuration/service-discovery.md diff --git a/docs/reference/rack/registry.md b/docs/deployment/custom-domains.md similarity index 100% rename from docs/reference/rack/registry.md rename to docs/deployment/custom-domains.md diff --git a/docs/deployment/rollbacks.md b/docs/deployment/rollbacks.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/deployment/rolling-updates.md b/docs/deployment/rolling-updates.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/deployment/scaling.md b/docs/deployment/scaling.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/development/code-sync.md b/docs/development/code-sync.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/development/local-development.md b/docs/development/local-development.md new file mode 100644 index 0000000..5de4888 --- /dev/null +++ b/docs/development/local-development.md @@ -0,0 +1,5 @@ +--- +order: 1 +--- + +# Local Development diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/getting-started/introduction.md b/docs/getting-started/introduction.md new file mode 100644 index 0000000..a625304 --- /dev/null +++ b/docs/getting-started/introduction.md @@ -0,0 +1,5 @@ +--- +order: 1 +--- + +# Introduction \ No newline at end of file diff --git a/docs/help/support.md b/docs/help/support.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/help/troubleshooting.md b/docs/help/troubleshooting.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/guides/installation/cli.md b/docs/installation/cli.md similarity index 84% rename from docs/guides/installation/cli.md rename to docs/installation/cli.md index 08a4e06..25238b8 100644 --- a/docs/guides/installation/cli.md +++ b/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 \ No newline at end of file + $ sudo chmod 755 /usr/local/bin/convox diff --git a/docs/installation/development-rack.md b/docs/installation/development-rack.md new file mode 100644 index 0000000..9ef9cc2 --- /dev/null +++ b/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` \ No newline at end of file diff --git a/docs/installation/production-rack/README.md b/docs/installation/production-rack/README.md new file mode 100644 index 0000000..9805d4f --- /dev/null +++ b/docs/installation/production-rack/README.md @@ -0,0 +1 @@ +# Production Rack diff --git a/docs/installation/production-rack/aws.md b/docs/installation/production-rack/aws.md new file mode 100644 index 0000000..9b6369e --- /dev/null +++ b/docs/installation/production-rack/aws.md @@ -0,0 +1 @@ +# Amazon Web Services diff --git a/docs/installation/production-rack/azure.md b/docs/installation/production-rack/azure.md new file mode 100644 index 0000000..74a5ad1 --- /dev/null +++ b/docs/installation/production-rack/azure.md @@ -0,0 +1 @@ +# Microsoft Azure diff --git a/docs/installation/production-rack/do.md b/docs/installation/production-rack/do.md new file mode 100644 index 0000000..86bdc56 --- /dev/null +++ b/docs/installation/production-rack/do.md @@ -0,0 +1 @@ +# Digital Ocean diff --git a/docs/installation/production-rack/gcp.md b/docs/installation/production-rack/gcp.md new file mode 100644 index 0000000..12ee8bd --- /dev/null +++ b/docs/installation/production-rack/gcp.md @@ -0,0 +1 @@ +# Google Cloud diff --git a/docs/integrations/ci/README.md b/docs/integrations/ci/README.md new file mode 100644 index 0000000..257fa0f --- /dev/null +++ b/docs/integrations/ci/README.md @@ -0,0 +1 @@ +# Continuous Integration diff --git a/docs/integrations/ci/circleci.md b/docs/integrations/ci/circleci.md new file mode 100644 index 0000000..56fa4e3 --- /dev/null +++ b/docs/integrations/ci/circleci.md @@ -0,0 +1 @@ +# CircleCI diff --git a/docs/integrations/ci/github-actions.md b/docs/integrations/ci/github-actions.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/integrations/logging/README.md b/docs/integrations/logging/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/integrations/logging/logdna.md b/docs/integrations/logging/logdna.md new file mode 100644 index 0000000..74be49b --- /dev/null +++ b/docs/integrations/logging/logdna.md @@ -0,0 +1 @@ +# LogDNA diff --git a/docs/integrations/logging/loggly.md b/docs/integrations/logging/loggly.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/integrations/logging/papertrail.md b/docs/integrations/logging/papertrail.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/integrations/monitoring/README.md b/docs/integrations/monitoring/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/integrations/monitoring/datadog.md b/docs/integrations/monitoring/datadog.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/management/logging.md b/docs/management/logging.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/management/private-registries.md b/docs/management/private-registries.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/app/primitives.md b/docs/reference/app/primitives.md deleted file mode 100644 index 85ee74f..0000000 --- a/docs/reference/app/primitives.md +++ /dev/null @@ -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 | diff --git a/docs/reference/cli/README.md b/docs/reference/cli/README.md new file mode 100644 index 0000000..79aafc4 --- /dev/null +++ b/docs/reference/cli/README.md @@ -0,0 +1 @@ +# CLI Commands diff --git a/docs/reference/cli/api.md b/docs/reference/cli/api.md new file mode 100644 index 0000000..ce92ada --- /dev/null +++ b/docs/reference/cli/api.md @@ -0,0 +1,23 @@ +# api + +## api get + +Query the Rack API + +### Usage + + convox api get + +### Examples + + $ convox api get /apps + [ + { + "generation": "3", + "locked": false, + "name": "myapp", + "release": "RABCDEFGHI", + "router", "0a1b2c3d4e5f.convox.cloud", + "status": "running" + } + ] \ No newline at end of file diff --git a/docs/reference/primitives/README.md b/docs/reference/primitives/README.md new file mode 100644 index 0000000..a817f74 --- /dev/null +++ b/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 | \ No newline at end of file diff --git a/docs/reference/app.md b/docs/reference/primitives/app/README.md similarity index 100% rename from docs/reference/app.md rename to docs/reference/primitives/app/README.md diff --git a/docs/reference/app/primitives/balancer.md b/docs/reference/primitives/app/balancer.md similarity index 100% rename from docs/reference/app/primitives/balancer.md rename to docs/reference/primitives/app/balancer.md diff --git a/docs/reference/app/primitives/build.md b/docs/reference/primitives/app/build.md similarity index 100% rename from docs/reference/app/primitives/build.md rename to docs/reference/primitives/app/build.md diff --git a/docs/reference/app/primitives/object.md b/docs/reference/primitives/app/object.md similarity index 100% rename from docs/reference/app/primitives/object.md rename to docs/reference/primitives/app/object.md diff --git a/docs/reference/app/primitives/process.md b/docs/reference/primitives/app/process.md similarity index 100% rename from docs/reference/app/primitives/process.md rename to docs/reference/primitives/app/process.md diff --git a/docs/reference/app/primitives/release.md b/docs/reference/primitives/app/release.md similarity index 100% rename from docs/reference/app/primitives/release.md rename to docs/reference/primitives/app/release.md diff --git a/docs/reference/app/primitives/resource.md b/docs/reference/primitives/app/resource.md similarity index 100% rename from docs/reference/app/primitives/resource.md rename to docs/reference/primitives/app/resource.md diff --git a/docs/reference/app/primitives/service.md b/docs/reference/primitives/app/service.md similarity index 84% rename from docs/reference/app/primitives/service.md rename to docs/reference/primitives/app/service.md index 19e2e18..3205b76 100644 --- a/docs/reference/app/primitives/service.md +++ b/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 diff --git a/docs/reference/primitives/rack/README.md b/docs/reference/primitives/rack/README.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/primitives/rack/instance.md b/docs/reference/primitives/rack/instance.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/primitives/rack/registry.md b/docs/reference/primitives/rack/registry.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/reference/security.md b/docs/reference/security.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/tutorials/deploying-an-application.md b/docs/tutorials/deploying-an-application.md new file mode 100644 index 0000000..44af75c --- /dev/null +++ b/docs/tutorials/deploying-an-application.md @@ -0,0 +1 @@ +# Deploying an Application