From 7e9118a4247ec6f5e768049aec0f9dda3b7e055d Mon Sep 17 00:00:00 2001 From: David Dollar Date: Tue, 28 Jan 2020 13:42:49 -0500 Subject: [PATCH] wip --- docs/configuration/convox.yml.md | 106 ++++++++++++++++++ docs/configuration/dockerfile.md | 64 +++++++++++ docs/configuration/health-checks.md | 39 +++++++ .../{load-balancing.md => load-balancers.md} | 2 +- docs/configuration/logging.md | 25 +++++ docs/configuration/private-registries.md | 21 ++++ docs/deployment/custom-domains.md | 41 +++++++ docs/development/code-sync.md | 0 docs/development/local-development.md | 5 - docs/development/running-locally.md | 74 ++++++++++++ docs/getting-started/concepts.md | 0 docs/installation/cli.md | 2 +- docs/installation/development-rack.md | 71 ------------ docs/installation/development-rack/README.md | 9 ++ docs/installation/development-rack/macos.md | 42 +++++++ docs/installation/development-rack/ubuntu.md | 43 +++++++ docs/installation/production-rack/README.md | 9 ++ docs/installation/production-rack/aws.md | 42 +++++++ docs/installation/production-rack/azure.md | 45 ++++++++ docs/installation/production-rack/do.md | 31 +++++ docs/installation/production-rack/gcp.md | 48 ++++++++ .../webhooks.md} | 0 docs/management/logging.md | 0 docs/management/private-registries.md | 0 docs/reference/cli/README.md | 2 +- docs/reference/primitives/app/service.md | 5 - docs/reference/security.md | 0 docs/tutorials/deploying-an-application.md | 4 + docs/tutorials/local-development.md | 5 + 29 files changed, 651 insertions(+), 84 deletions(-) rename docs/configuration/{load-balancing.md => load-balancers.md} (98%) create mode 100644 docs/configuration/logging.md create mode 100644 docs/configuration/private-registries.md delete mode 100644 docs/development/code-sync.md delete mode 100644 docs/development/local-development.md create mode 100644 docs/development/running-locally.md delete mode 100644 docs/getting-started/concepts.md delete mode 100644 docs/installation/development-rack.md create mode 100644 docs/installation/development-rack/README.md create mode 100644 docs/installation/development-rack/macos.md create mode 100644 docs/installation/development-rack/ubuntu.md rename docs/{configuration/persistent-storage.md => integrations/webhooks.md} (100%) delete mode 100644 docs/management/logging.md delete mode 100644 docs/management/private-registries.md delete mode 100644 docs/reference/security.md create mode 100644 docs/tutorials/local-development.md diff --git a/docs/configuration/convox.yml.md b/docs/configuration/convox.yml.md index 1f02528..3c5cc54 100644 --- a/docs/configuration/convox.yml.md +++ b/docs/configuration/convox.yml.md @@ -3,3 +3,109 @@ order: 1 --- # convox.yml + +`convox.yml` is a manifest used to describe your application and all of its infrastructure needs. + + environment: + - COMPANY=Convox + - DOCS_URL + resources: + database: + type: postgres + options: + storage: 200 + queue: + type: redis + services: + api: + build: . + command: bin/api + environment: + - ENCRYPTION_KEY + health: /check + internal: true + port: 3000 + resources: + - database + - queue + test: make test + web: + build: . + command: bin/web + environment: + - SESSION_SECRET + port: 3000 + worker: + build: ./worker + command: bin/worker + environment: + - ENCRYPTION_KEY + resources: + - database + - queue + metrics: + agent: true + image: awesome/metrics + timers: + cleanup: + schedule: "0 3 * * ? *" + command: bin/cleanup + service: worker + +## environment + +The top-level `environment` section defines [Environment Variables](environment.md) that are available to every +[Service](../reference/primitives/app/service.md). + + environment: + - COMPANY=Convox # has a default value of "Convox" + - DOCS_URL # must be set before deployment + +See [Environment Variables](environment.md) for configuration options. + +## resources + +The `resources` section defines network-accessible [Resources](../reference/primitives/app/resource.md) +such as databases that can be made available to [Services](../references/primitives/app/service.md). + + resources: + database: + type: postgres + options: + storage: 200 + +See [Resource](../reference/primitives/app/resource.md) for configuration options. + +## services + +The `services` section horizontally-scalable [Services](../reference/primitives/app/service.md) +that can be optionally placed behind a load balancer. + + services: + api: + build: . + command: bin/api + environment: + - ENCRYPTION_KEY + health: /check + internal: true + port: 3000 + resources: + - database + - queue + test: make test + +See [Service](../reference/primitives/app/service.md) for configuration options. + +## timers + +The `timers` section defines [Processes](../reference/primitives/app/process.md) +that run periodically on a set interval. + + timers: + cleanup: + schedule: "0 3 * * ? *" + command: bin/cleanup + service: worker + +See [Timer](../reference/primitives/app/timer.md) for configuration options. diff --git a/docs/configuration/dockerfile.md b/docs/configuration/dockerfile.md index e69de29..50d9212 100644 --- a/docs/configuration/dockerfile.md +++ b/docs/configuration/dockerfile.md @@ -0,0 +1,64 @@ +--- +order: 2 +--- + +# Dockerfile + +The `Dockerfile` describes the steps used to create a [Build](../reference/primitives/app/build.md) from your +application code. + + FROM ubuntu:18.04 + COPY . . + RUN ["deps", "install"] + CMD ["bin/start"] + +## Common Directives + +| Directive | Description | +| --------- | ------------------------------------------------ | +| `FROM` | defines the base image | +| `COPY` | add files from the local directory tree | +| `RUN` | execute a command | +| `CMD` | defines the default command to run on this image | +| `ARG` | define build variables | + +## Optimizing Build Times + +Each line of a `Dockerfile` will be cached as long as files referenced by it are not changed. This allows you +to cache expensive steps such as dependency installation by selectively copying files before running commands. + +The following example selectively copies only the files needed to run `npm` before installing dependencies. + + FROM nodejs + + COPY package.json package-lock.json . + RUN ["npm", "install"] + + COPY . . + CMD ["npm", "start"] + +The `npm install` will be cached on successive builds unless `package.json` or `package-lock.json` is changed. + +## Build Variables + +Convox respects the `ARG` directive, allowing you to specify variables at build time. + +This is useful for creating dynamic build environments, allowing you to use the same Dockerfile for varying +deployments. + +> It is not recommended to use build variables for passing secrets. Values for build variables are embedded +> in the resulting image. + +You can declare build variables using the `ARG` directive with an optional default value: + + ARG COPYRIGHT=2020 + ARG RUBY_VERSION + +Values for these variables will be read from the [Environment](environment.md) at build time: + + $ convox env set RUBY_VERSION=2.6.4 + +## See Also + +- [Dockerfile: Best Practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/) +- [Private Registries](private-registries.md) \ No newline at end of file diff --git a/docs/configuration/health-checks.md b/docs/configuration/health-checks.md index e69de29..2e92e8d 100644 --- a/docs/configuration/health-checks.md +++ b/docs/configuration/health-checks.md @@ -0,0 +1,39 @@ +# Health Checks + +Deploying a [Service](../reference/primitives/app/service.md) behind a load balancer requires a health +check to determine whether a given [Process](../reference/primitives/app/process.md) is ready to +handle requests. + +Health checks must return a valid HTTP response code (200-399) within the configured `timeout`. + +[Processes](../reference/primitives/app/process.md) that fail two health checks in a row are assumed +dead and will be terminated and replaced. + +## Definition + +### Simple + + services: + web: + health: /check + +> Specifying `health` as a string will set the `path` and leave the other options as defaults. + +### Advanced + +``` +services: + web: + health: + grace: 5 + interval: 5 + path: /check + timeout: 3 +``` + +| Attribute | Default | Description | +| ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ | +| `grace` | 5 | The amount of time in seconds to wait for a [Process](../reference/primitives/app/process.md) to boot before beginning health checks | +| `interval` | 5 | The number of seconds between health checks | +| `path` | / | The HTTP endpoint that will be requested | +| `timeout` | 4 | The number of seconds to wait for a valid response | \ No newline at end of file diff --git a/docs/configuration/load-balancing.md b/docs/configuration/load-balancers.md similarity index 98% rename from docs/configuration/load-balancing.md rename to docs/configuration/load-balancers.md index b4f7814..253c5f9 100644 --- a/docs/configuration/load-balancing.md +++ b/docs/configuration/load-balancers.md @@ -1,4 +1,4 @@ -# Load Balancing +# Load Balancers ## Standard Load Balancer diff --git a/docs/configuration/logging.md b/docs/configuration/logging.md new file mode 100644 index 0000000..3c48b79 --- /dev/null +++ b/docs/configuration/logging.md @@ -0,0 +1,25 @@ +# Logging + +Convox automatically captures and stores logs for: + +* All output to `stdout` or `stderr` made by any running [Process](../reference/primitives/app/process.md) +* State changes triggered by deployments +* Health check failures + +## Command Line Interface + +### Viewing Logs for an App + +#### Simple + + $ convox logs -a myapp + 2020-01-01T00:00:00Z service/web/012345689 starting on port 3000 + 2020-01-01T00:00:01Z service/web/012345689 GET / 200 + 2020-01-01T00:00:02Z service/web/012345689 GET /other 404 + +#### Advanced + + $ convox logs -a myapp --since 20m --no-follow + 2020-01-01T00:00:00Z service/web/012345689 starting on port 3000 + 2020-01-01T00:00:01Z service/web/012345689 GET / 200 + 2020-01-01T00:00:02Z service/web/012345689 GET /other 404 diff --git a/docs/configuration/private-registries.md b/docs/configuration/private-registries.md new file mode 100644 index 0000000..7c94594 --- /dev/null +++ b/docs/configuration/private-registries.md @@ -0,0 +1,21 @@ +# Private Registries + +Convox can pull base images from private registries during the build process. + +## Command Line Interface + +### Adding a Registry + + $ convox registries add registry.example.org username password + Adding registry... OK + +### Listing Registries + + $ convox registries + SERVER USERNAME + registry.example.org username + +### Removing a Registry + + $ convox registries remove registry.example.org + Removing registry... OK \ No newline at end of file diff --git a/docs/deployment/custom-domains.md b/docs/deployment/custom-domains.md index e69de29..a4f7c20 100644 --- a/docs/deployment/custom-domains.md +++ b/docs/deployment/custom-domains.md @@ -0,0 +1,41 @@ +# Custom Domains + +Custom domains allow you to route one or more domains to a [Service](../reference/primitives/app/service.md). + +## Definition + + services: + web: + domain: myapp.example.org + +### Wildcard Domains + + services: + web: + domain: "*.example.org" + +> YAML requires strings beginning with `*` to be enclosed in quotes. + +### Dynamic Configuration + +You can avoid hardcoding your custom domains in `convox.yml` using +[Environment Interpolation](../configuration/environment#interpolation). + + services: + web: + domain: ${HOST} + +``` +$ convox env set HOST=myapp.example.org,myapp2.example.org +``` + +## Configuring DNS + + $ convox rack + Name production + Provider aws + Router router.0a1b2c3d4e5f.convox.cloud + Status running + +Configure your DNS to point your custom domain as a `CNAME` to the `Router` for +your [Rack](../reference/primitives/rack). \ No newline at end of file diff --git a/docs/development/code-sync.md b/docs/development/code-sync.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/development/local-development.md b/docs/development/local-development.md deleted file mode 100644 index 5de4888..0000000 --- a/docs/development/local-development.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -order: 1 ---- - -# Local Development diff --git a/docs/development/running-locally.md b/docs/development/running-locally.md new file mode 100644 index 0000000..17f0bad --- /dev/null +++ b/docs/development/running-locally.md @@ -0,0 +1,74 @@ +--- +order: 1 +--- + +# Running Locally + +Running your application locally requires a [Development Rack](../instalation/development-rack) to be installed. + +## Starting Your Application + +Once you have a Development Rack, you can go to the directory containing your application code and run `convox start`. + + $ convox start + build | uploading source + build | starting build + build | Authenticating registry.dev.convox/convox: Login Succeeded + build | Building: . + build | Sending build context to Docker daemon 114.4MB + build | Step 1/5 : FROM golang:1.13 AS development + build | ---> 272e3f68338f + build | Step 2/5 : ENV DEVELOPMENT=true + build | ---> 8323381038aa + build | Step 3/5 : COPY . . + build | ---> e87c93ad5c25 + build | Step 4/5 : RUN go install ./cmd/web + build | ---> 0be9da9a42c6 + build | Step 5/5 : CMD ["bin/development", "web"] + build | ---> e87c93ad5c25 + build | Successfully built e87c93ad5c25 + build | Successfully tagged 66608a93037391937ae7bdd4e148189d1369d38e:latest + build | Running: docker tag 66608a93037391937ae7bdd4e148189d1369d38e dev/myapp:web.BABCDEFGHI + build | Running: docker tag dev/myapp:web.BABCDEFGHI registry.dev.convox/myapp:web.BABCDEFGHI + build | Running: docker push registry.dev.convox/myapp:web.BABCDEFGHI + convox | starting sync from . to . on web + web | Scaled up replica set web-786b6d8f5d to 1 + web | Created pod: web-786b6d8f5d-l9jd2 + web | Successfully assigned dev-convox/web-786b6d8f5d-l9jd2 to docker-desktop + web | Container image "registry.dev.convox/myapp:web.BABCDEFGHI" already present on machine + web | Created container main + web | make: '/go/bin/web' is up to date. + web | ns=web at=listen hostname="web.convox" proto="https" addr=":3000" + +### Code Sync + +Convox automatically synchronizes your local changes up to the Development Rack so that you can work +using your favorite editor. + +All files or directories that appear in a `COPY` or `ADD` directive in your `Dockerfile` will be +synchronized. + +> Files or directories that appear in `.dockerignore` will not be synchronized. + +## Development Target + +You can use a build target named `development` in your `Dockerfile` to work locally on an application that will be +later compiled to a binary and have its source code removed before deploying to production. + + FROM golang:1.13 AS development + ENV DEVELOPMENT=true + COPY . . + RUN go install ./cmd/web + CMD ["bin/development", "web"] + + FROM ubuntu:18.04 as production + ENV DEVELOPMENT=false + COPY --from=development /go/bin/web /app/web + CMD ["/app/web"] + +In this example during `convox start` only the first section of the Dockerfile will be run. This allows you to +work in a container that contains the full source code where you can set `CMD` to a script that automatically +recompiles and reloads the application when the source code is changed. + +When deploying to production the entire Dockerfile would be run and you would end up with a bare `ubuntu:18.04` container +with only the compiled binary copied into it. \ No newline at end of file diff --git a/docs/getting-started/concepts.md b/docs/getting-started/concepts.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/installation/cli.md b/docs/installation/cli.md index 25238b8..39065a0 100644 --- a/docs/installation/cli.md +++ b/docs/installation/cli.md @@ -6,7 +6,7 @@ $ sudo mv /tmp/convox /usr/local/bin/convox $ sudo chmod 755 /usr/local/bin/convox -## MacOS +## macOS $ curl -L https://github.com/convox/convox/releases/latest/download/convox-macos -o /tmp/convox $ sudo mv /tmp/convox /usr/local/bin/convox diff --git a/docs/installation/development-rack.md b/docs/installation/development-rack.md deleted file mode 100644 index 9ef9cc2..0000000 --- a/docs/installation/development-rack.md +++ /dev/null @@ -1,71 +0,0 @@ -# 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/development-rack/README.md b/docs/installation/development-rack/README.md new file mode 100644 index 0000000..33be415 --- /dev/null +++ b/docs/installation/development-rack/README.md @@ -0,0 +1,9 @@ +# Development Rack + +A development Rack is runs on your local workstation and allows you to work on your +[App](../../reference/primitives/app) in an environment identical to production. + +## Installation + +- [macOS](macos.md) +- [Ubuntu](ubuntu.md) \ No newline at end of file diff --git a/docs/installation/development-rack/macos.md b/docs/installation/development-rack/macos.md new file mode 100644 index 0000000..07f4d09 --- /dev/null +++ b/docs/installation/development-rack/macos.md @@ -0,0 +1,42 @@ +# macOS + +## Initial Setup + +### Kubernetes + +- 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 + +### Convox CLI + + $ 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 + +## Installation + +Install a local Rack named `dev`. + + $ convox rack install local dev + +## DNS Setup + +Set `*.convox` to be resolved by the local Rack's DNS server. + + $ sudo mkdir -p /etc/resolver + $ sudo bash -c 'echo "nameserver 127.0.0.1" > /etc/resolver/convox' + +## 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. + + $ 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 \ No newline at end of file diff --git a/docs/installation/development-rack/ubuntu.md b/docs/installation/development-rack/ubuntu.md new file mode 100644 index 0000000..e493c3b --- /dev/null +++ b/docs/installation/development-rack/ubuntu.md @@ -0,0 +1,43 @@ +# Ubuntu + +## Initial Setup + +### Kubernetes + + $ snap install microk8s --classic --channel=1.13/stable + $ microk8s.enable dns storage + $ mkdir -p ~/.kube + $ microk8s.config > ~/.kube/config + $ sudo snap restart microk8s + +### Convox CLI + + $ curl -L https://github.com/convox/convox/releases/latest/download/convox-linux -o /tmp/convox + $ sudo mv /tmp/convox /usr/local/bin/convox + $ sudo chmod 755 /usr/local/bin/convox + +## Installation + +Install a local Rack named `dev`. + + $ convox rack install local dev + +## DNS Setup + +Set `*.convox` to be resolved by the local Rack's DNS server. + + $ 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. + + $ 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 index 9805d4f..24a0944 100644 --- a/docs/installation/production-rack/README.md +++ b/docs/installation/production-rack/README.md @@ -1 +1,10 @@ # Production Rack + +A production Rack runs on a cloud provider. + +## Select a Provider + +- [Amazon Web Services](aws.md) +- [Digital Ocean](do.md) +- [Google Cloud](gcp.md) +- [Microsoft Azure](azure.md) \ No newline at end of file diff --git a/docs/installation/production-rack/aws.md b/docs/installation/production-rack/aws.md index 9b6369e..c630a06 100644 --- a/docs/installation/production-rack/aws.md +++ b/docs/installation/production-rack/aws.md @@ -1 +1,43 @@ # Amazon Web Services + +## Initial Setup + +### AWS CLI + +- [Install the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-install.html) + +### Convox CLI + +- [Install the Convox CLI](../cli.md) + +## Environment + +The following environment variables are required: + +- `AWS_ACCESS_KEY_ID` +- `AWS_DEFAULT_REGION` +- `AWS_SECRET_ACCESS_KEY` + +### Select Region + +You can list all available regions for your account with the following command: + + $ aws ec2 describe-regions --all-regions + +- `AWS_DEFAULT_REGION` is `RegionName` + +### Create IAM User + + $ aws iam create-user --user-name convox + $ aws iam create-access-key --user-name convox + +- `AWS_ACCESS_KEY_ID` is `AccessKeyId` +- `AWS_SECRET_ACCESS_KEY` is `SecretAccessKey` + +### Grant Permissions + + $ aws iam attach-user-policy --user-name convox --policy-arn arn:aws:iam::aws:policy/AdministratorAccess + +## Install Rack + + $ convox rack install aws diff --git a/docs/installation/production-rack/azure.md b/docs/installation/production-rack/azure.md index 74a5ad1..829d338 100644 --- a/docs/installation/production-rack/azure.md +++ b/docs/installation/production-rack/azure.md @@ -1 +1,46 @@ # Microsoft Azure + +## Initial Setup + +### Azure CLI + +- [Install the Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) +- Run `az login` + +### Convox CLI + +- [Install the Convox CLI](../cli.md) + +## Environment + +The following environment variables are required: + +- `ARM_CLIENT_ID` +- `ARM_CLIENT_SECRET` +- `ARM_SUBSCRIPTION_ID` +- `ARM_TENANT_ID` + +### Select Subscription + + $ az account list + +- `ARM_SUBSCRIPTION_ID` is the `id` +- `ARM_TENANT_ID` is the `tenantId` + +### Create Service Principal + + $ az account set --subscription="$ARM_SUBSCRIPTION_ID" + $ az ad sp create-for-rbac --name=terraform --role=Owner --scopes="/subscriptions/$ARM_SUBSCRIPTION_ID" + +- `ARM_CLIENT_ID` is the `appId` +- `ARM_CLIENT_SECRET` is the `password` + +### Grant Permissions + + $ az ad app permission add --id $ARM_CLIENT_ID --api 00000002-0000-0000-c000-000000000000 --api-permissions 311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope 824c81eb-e3f8-4ee6-8f6d-de7f50d565b7=Role + $ az ad app permission grant --id $ARM_CLIENT_ID --api 1489bf2e-4a8b-43c5-a319-8eda31218f4c --consent-type AllPrincipals --scope User.Read + $ az ad app permission admin-consent --id $ARM_CLIENT_ID + +## Install Rack + + $ convox rack install azure \ No newline at end of file diff --git a/docs/installation/production-rack/do.md b/docs/installation/production-rack/do.md index 86bdc56..6292bfd 100644 --- a/docs/installation/production-rack/do.md +++ b/docs/installation/production-rack/do.md @@ -1 +1,32 @@ # Digital Ocean + +## Initial Setup + +### Convox CLI + +- [Install the Convox CLI](../cli.md) + +## Environment + +The following environment variables are required: + +- `DIGITALOCEAN_ACCESS_ID` +- `DIGITALOCEAN_SECRET_KEY` +- `DIGITALOCEAN_TOKEN` + +### Create Token + +Go to https://cloud.digitalocean.com/account/api/tokens and generate a new Personal Access Token. + +- `DIGITALOCEAN_TOKEN` is the token you just created + +### Create Spaces Access Key + +Go to https://cloud.digitalocean.com/account/api/tokens and generate a new Spaces Access Key. + +- `DIGITALOCEAN_ACCESS_ID` is the resulting Key +- `DIGITALOCEAN_SECRET_KEY` is the Secret + +## Install Rack + + $ convox rack install do \ No newline at end of file diff --git a/docs/installation/production-rack/gcp.md b/docs/installation/production-rack/gcp.md index 12ee8bd..33b639d 100644 --- a/docs/installation/production-rack/gcp.md +++ b/docs/installation/production-rack/gcp.md @@ -1 +1,49 @@ # Google Cloud + +## Initial Setup + +### Google Cloud CLI + +- [Install the Google Cloud CLI](https://cloud.google.com/sdk/docs/#install_the_latest_cloud_tools_version_cloudsdk_current_version) +- Run `gcloud init` + +### Convox CLI + +- [Install the Convox CLI](../cli.md) + +## Environment + +The following environment variables are required: + +- `GOOGLE_CREDENTIALS` +- `GOOGLE_PROJECT` +- `GOOGLE_REGION` + +### Select Region + + $ gcloud compute regions list + +- `GOOGLE_REGION` is a region `NAME` from the list + +### Create Project + + $ gcloud projects create --set-as-default + +- `GOOGLE_PROJECT` is the id you selected + +> You will likely need to set up Billing on this new project at https://console.cloud.google.com/billing before proceeding + +### Create Service Account + + $ serviceaccount=$(gcloud iam service-accounts create convox --format="value(email)") + $ gcloud iam service-accounts keys create ~/gcloud.convox --iam-account=${serviceaccount} + +- `GOOGLE_CREDENTIALS` is `~/gcloud.convox` + +### Grant Permissions + + $ gcloud projects add-iam-policy-binding $GOOGLE_PROJECT --member=serviceAccount:${serviceaccount} --role=roles/owner + +## Install Rack + + $ convox rack install gcp diff --git a/docs/configuration/persistent-storage.md b/docs/integrations/webhooks.md similarity index 100% rename from docs/configuration/persistent-storage.md rename to docs/integrations/webhooks.md diff --git a/docs/management/logging.md b/docs/management/logging.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/management/private-registries.md b/docs/management/private-registries.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/reference/cli/README.md b/docs/reference/cli/README.md index 79aafc4..06b3e9f 100644 --- a/docs/reference/cli/README.md +++ b/docs/reference/cli/README.md @@ -1 +1 @@ -# CLI Commands +# Command Line Interface \ No newline at end of file diff --git a/docs/reference/primitives/app/service.md b/docs/reference/primitives/app/service.md index 3205b76..5071507 100644 --- a/docs/reference/primitives/app/service.md +++ b/docs/reference/primitives/app/service.md @@ -8,8 +8,6 @@ Services can be scaled to a static count or autoscaled in a range based on metri ## Definition -A Service is defined in [`convox.yml`](../convox.yml.md). - ``` services: web: @@ -53,8 +51,6 @@ services: singleton: false sticky: true test: make test - volumes: - - /shared ``` | Attribute | Type | Default | Description | @@ -75,7 +71,6 @@ services: | `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` | -| `volumes` | list | | A list of directories to share between [Processes](process.md) of this Service | > Environment variables **must** be declared to be populated for a Service. diff --git a/docs/reference/security.md b/docs/reference/security.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/tutorials/deploying-an-application.md b/docs/tutorials/deploying-an-application.md index 44af75c..bf2c114 100644 --- a/docs/tutorials/deploying-an-application.md +++ b/docs/tutorials/deploying-an-application.md @@ -1 +1,5 @@ +--- +order: 2 +--- + # Deploying an Application diff --git a/docs/tutorials/local-development.md b/docs/tutorials/local-development.md new file mode 100644 index 0000000..e3e0308 --- /dev/null +++ b/docs/tutorials/local-development.md @@ -0,0 +1,5 @@ +--- +order: 1 +--- + +# Local Development \ No newline at end of file