Merge pull request #119 from basecamp/kamal-2.1.0

Doc updates for Kamal 2.1

_data/github.yml

@@ -1,3 +1,3 @@
-tag_name: 2.0.0
+tag_name: 2.1.0
 v1:
-  tag_name: 1.9.0
+  tag_name: 1.9.1

_data/nav.yml

@@ -1,9 +1,9 @@
 - title: "Documentation"
   url: /docs/
   options:
-  - title: "Version 2.0.0"
+  - title: "Version 2.1.0"
     url: /docs/
-  - title: "Version 1.9.0"
+  - title: "Version 1.9.1"
     url: /v1/docs/
 
 - title: "Source code"

docs/commands/version.md

@@ -8,5 +8,5 @@ Returns the version of Kamal you have installed.
 
 ```bash
 $ kamal version
-2.0.0
+2.1.0
 ```

docs/configuration/accessories.md

@@ -1,14 +1,19 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/accessory.yml in the Kamal repository.
 title: Accessories
 ---
 
 # Accessories
 
-Accessories can be booted on a single host, a list of hosts, or on specific roles. The hosts do not need to be defined in the Kamal servers configuration.
+Accessories can be booted on a single host, a list of hosts, or on specific roles.
+The hosts do not need to be defined in the Kamal servers configuration.
 
-Accessories are managed separately from the main service — they are not updated when you deploy, and they do not have zero-downtime deployments.
+Accessories are managed separately from the main service — they are not updated
+when you deploy, and they do not have zero-downtime deployments.
 
-Run `kamal accessory boot <accessory>` to boot an accessory. See `kamal accessory --help` for more information.
+Run `kamal accessory boot <accessory>` to boot an accessory.
+See `kamal accessory --help` for more information.
 
 ## [Configuring accessories](#configuring-accessories)
 
@@ -21,7 +26,8 @@ accessories:
 
 ## [Service name](#service-name)
 
-This is used in the service label and defaults to `<service>-<accessory>`, where `<service>` is the main service name from the root configuration:
+This is used in the service label and defaults to `<service>-<accessory>`,
+where `<service>` is the main service name from the root configuration:
 
 ```yaml
     service: mysql
@@ -58,7 +64,8 @@ You can set a custom command to run in the container if you do not want to use t
 
 ## [Port mappings](#port-mappings)
 
-See https://docs.docker.com/network/, and especially note the warning about the security implications of exposing ports publicly.
+See https://docs.docker.com/network/, and especially note the warning about the security
+implications of exposing ports publicly.
 
 ```yaml
     port: "127.0.0.1:3306:3306"
@@ -92,7 +99,9 @@ See [Environment variables](../environment-variables) for more information:
 
 ## [Copying files](#copying-files)
 
-You can specify files to mount into the container. The format is `local:remote`, where `local` is the path to the file on the local machine and `remote` is the path to the file in the container.
+You can specify files to mount into the container.
+The format is `local:remote`, where `local` is the path to the file on the local machine
+and `remote` is the path to the file in the container.
 
 They will be uploaded from the local repo to the host and then mounted.
 
@@ -106,7 +115,8 @@ ERB files will be evaluated before being copied.
 
 ## [Directories](#directories)
 
-You can specify directories to mount into the container. They will be created on the host before being mounted:
+You can specify directories to mount into the container. They will be created on the host
+before being mounted:
 
 ```yaml
     directories:
@@ -115,7 +125,8 @@ You can specify directories to mount into the container. They will be created on
 
 ## [Volumes](#volumes)
 
-Any other volumes to mount, in addition to the files and directories. They are not created or copied before mounting:
+Any other volumes to mount, in addition to the files and directories.
+They are not created or copied before mounting:
 
 ```yaml
     volumes:

docs/configuration/aliases.md

@@ -1,4 +1,6 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/alias.yml in the Kamal repository.
 title: Aliases
 ---
 

docs/configuration/booting.md

@@ -1,4 +1,6 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/boot.yml in the Kamal repository.
 title: Booting
 ---
 

docs/configuration/builders.md

@@ -1,4 +1,6 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/builder.yml in the Kamal repository.
 title: Builder
 ---
 
@@ -29,15 +31,17 @@ Allowed values are `amd64` and `arm64`:
 
 ## [Remote](#remote)
 
-The connection string for a remote builder. If supplied, Kamal will use this for builds that do not match the local architecture of the deployment host.
+The connection string for a remote builder. If supplied, Kamal will use this
+for builds that do not match the local architecture of the deployment host.
 
 ```yaml
   remote: ssh://docker@docker-builder
 ```
 
 ## [Local](#local)
 
-If set to false, Kamal will always use the remote builder even when building the local architecture.
+If set to false, Kamal will always use the remote builder even when building
+the local architecture.
 
 Defaults to true:
 
@@ -60,7 +64,8 @@ The image is only used for registry cache and is not compatible with the Docker
 
 ## [Build context](#build-context)
 
-If this is not set, then a local Git clone of the repo is used. This ensures a clean build with no uncommitted changes.
+If this is not set, then a local Git clone of the repo is used.
+This ensures a clean build with no uncommitted changes.
 
 To use the local checkout instead, you can set the context to `.`, or a path to another directory.
 
@@ -102,7 +107,7 @@ FROM ruby:$RUBY_VERSION-slim as base
 
 ## [Build secrets](#build-secrets)
 
-Values are read from .kamal/secrets.
+Values are read from `.kamal/secrets`:
 
 ```yaml
   secrets:

docs/configuration/docker-registry.md

@@ -1,12 +1,15 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/registry.yml in the Kamal repository.
 title: Registry
 ---
 
 # Registry
 
-The default registry is Docker Hub, but you can change it using `registry/server`:
+The default registry is Docker Hub, but you can change it using `registry/server`.
 
-A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret in the local environment.
+A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret
+in the local environment:
 
 ```yaml
 registry:
@@ -19,7 +22,8 @@ registry:
 
 ## [Using AWS ECR as the container registry](#using-aws-ecr-as-the-container-registry)
 
-You will need to have the AWS CLI installed locally for this to work. AWS ECR’s access token is only valid for 12 hours. In order to avoid having to manually regenerate the token every time, you can use ERB in the `deploy.yml` file to shell out to the AWS CLI command and obtain the token:
+You will need to have the AWS CLI installed locally for this to work.
+AWS ECR’s access token is only valid for 12 hours. In order to avoid having to manually regenerate the token every time, you can use ERB in the `deploy.yml` file to shell out to the AWS CLI command and obtain the token:
 
 ```yaml
 registry:
@@ -30,7 +34,10 @@ registry:
 
 ## [Using GCP Artifact Registry as the container registry](#using-gcp-artifact-registry-as-the-container-registry)
 
-To sign into Artifact Registry, you need to [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions). Normally, assigning the `roles/artifactregistry.writer` role should be sufficient.
+To sign into Artifact Registry, you need to
+[create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating)
+and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions).
+Normally, assigning the `roles/artifactregistry.writer` role should be sufficient.
 
 Once the service account is ready, you need to generate and download a JSON key and base64 encode it:
 
@@ -40,7 +47,8 @@ base64 -i /path/to/key.json | tr -d "\\n"
 
 You'll then need to set the `KAMAL_REGISTRY_PASSWORD` secret to that value.
 
-Use the environment variable as the password along with `_json_key_base64` as the username. Here’s the final configuration:
+Use the environment variable as the password along with `_json_key_base64` as the username.
+Here’s the final configuration:
 
 ```yaml
 registry:

docs/configuration/environment-variables.md

@@ -1,10 +1,13 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/env.yml in the Kamal repository.
 title: Environment variables
 ---
 
 # Environment variables
 
-Environment variables can be set directly in the Kamal configuration or read from `.kamal/secrets`.
+Environment variables can be set directly in the Kamal configuration or
+read from `.kamal/secrets`.
 
 ## [Reading environment variables from the configuration](#reading-environment-variables-from-the-configuration)
 
@@ -22,11 +25,13 @@ env:
 
 Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
 
-If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if it exists.
+If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if
+it exists.
 
 Common secrets across all destinations can be set in `.kamal/secrets-common`.
 
-This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords. You can use variable or command substitution in the secrets file.
+This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
+You can use variable or command substitution in the secrets file.
 
 ```shell
 KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
@@ -44,9 +49,11 @@ DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
 
 If you store secrets directly in `.kamal/secrets`, ensure that it is not checked into version control.
 
-To pass the secrets, you should list them under the `secret` key. When you do this, the other variables need to be moved under the `clear` key.
+To pass the secrets, you should list them under the `secret` key. When you do this, the
+other variables need to be moved under the `clear` key.
 
-Unlike clear values, secrets are not passed directly to the container but are stored in an env file on the host:
+Unlike clear values, secrets are not passed directly to the container
+but are stored in an env file on the host:
 
 ```yaml
 env:
@@ -58,7 +65,8 @@ env:
 
 ## [Tags](#tags)
 
-Tags are used to add extra env variables to specific hosts. See [Servers](../servers) for how to tag hosts.
+Tags are used to add extra env variables to specific hosts.
+See [Servers](../servers) for how to tag hosts.
 
 Tags are only allowed in the top-level env configuration (i.e., not under a role-specific env).
 

docs/configuration/logging.md

@@ -1,4 +1,6 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/logging.yml in the Kamal repository.
 title: Custom logging configuration
 ---
 

docs/configuration/overview.md

@@ -1,4 +1,6 @@
 ---
+# This file has been generated from the Kamal source, do not edit directly.
+# Find the source of this file at lib/kamal/configuration/docs/configuration.yml in the Kamal repository.
 title: Kamal Configuration
 ---
 
@@ -8,17 +10,21 @@ Configuration is read from the `config/deploy.yml`.
 
 ## [Destinations](#destinations)
 
-When running commands, you can specify a destination with the `-d` flag, e.g., `kamal deploy -d staging`.
+When running commands, you can specify a destination with the `-d` flag,
+e.g., `kamal deploy -d staging`.
 
-In this case, the configuration will also be read from `config/deploy.staging.yml` and merged with the base configuration.
+In this case, the configuration will also be read from `config/deploy.staging.yml`
+and merged with the base configuration.
 
 ## [Extensions](#extensions)
 
 Kamal will not accept unrecognized keys in the configuration file.
 
-However, you might want to declare a configuration block using YAML anchors and aliases to avoid repetition.
+However, you might want to declare a configuration block using YAML anchors
+and aliases to avoid repetition.
 
-You can prefix a configuration section with `x-` to indicate that it is an extension. Kamal will ignore the extension and not raise an error.
+You can prefix a configuration section with `x-` to indicate that it is an
+extension. Kamal will ignore the extension and not raise an error.
 
 ## [The service name](#the-service-name)
 
@@ -85,9 +91,14 @@ env:
 
 Used for asset bridging across deployments, default to `nil`.
 
-If there are changes to CSS or JS files, we may get requests for the old versions on the new container, and vice versa.
+If there are changes to CSS or JS files, we may get requests
+for the old versions on the new container, and vice versa.
 
-To avoid 404s, we can specify an asset path. Kamal will replace that path in the container with a mapped volume containing both sets of files. This requires that file names change when the contents change (e.g., by including a hash of the contents in the name).
+To avoid 404s, we can specify an asset path.
+Kamal will replace that path in the container with a mapped
+volume containing both sets of files.
+This requires that file names change when the contents change
+(e.g., by including a hash of the contents in the name).
 
 To configure this, set the path to the assets:
 
@@ -97,7 +108,8 @@ asset_path: /path/to/assets
 
 ## [Hooks path](#hooks-path)
 
-Path to hooks, defaults to `.kamal/hooks`. See [Hooks](/docs/hooks) for more information:
+Path to hooks, defaults to `.kamal/hooks`.
+See [Hooks](/docs/hooks) for more information:
 
 ```yaml
 hooks_path: /user_home/kamal/hooks
@@ -169,6 +181,14 @@ How long to wait for a container to drain, default 30:
 drain_timeout: 10
 ```
 
+## [Run directory](#run-directory)
+
+Directory to store kamal runtime files in on the host, default `.kamal`:
+
+```yaml
+run_directory: /etc/kamal
+```
+
 ## [SSH options](#ssh-options)
 
 See [SSH](../ssh):