diff --git a/_includes/nav.html b/_includes/nav.html
index 8751bc8..68a8369 100755
--- a/_includes/nav.html
+++ b/_includes/nav.html
@@ -1,14 +1,14 @@
{% if page.version == 'v1' %}
{% assign search_action = '/v1/docs/search/' %}
- {% assign search_placeholder = 'Search V1 docs...' %}
+ {% assign search_placeholder = 'Search v1 docs...' %}
{% assign data_docs = site.data.docs_v1 %}
{% else %}
{% assign search_action = '/docs/search/' %}
- {% assign search_placeholder = 'Search V2 docs...' %}
+ {% assign search_placeholder = 'Search v2 docs...' %}
{% assign data_docs = site.data.docs %}
diff --git a/_layouts/docs.html b/_layouts/docs.html
index 0bd66dc..8070b8a 100644
--- a/_layouts/docs.html
+++ b/_layouts/docs.html
@@ -15,14 +15,14 @@
{% if page.version == 'v1' %}
{% assign search_action = '/v1/docs/search/' %}
- {% assign search_placeholder = 'Search V1 docs...' %}
+ {% assign search_placeholder = 'Search v1 docs...' %}
{% assign data_docs = site.data.docs_v1 %}
{% else %}
{% assign search_action = '/docs/search/' %}
- {% assign search_placeholder = 'Search V2 docs...' %}
+ {% assign search_placeholder = 'Search v2 docs...' %}
{% assign data_docs = site.data.docs %}
diff --git a/_sass/modules/_footer.scss b/_sass/modules/_footer.scss
index 236d7a2..39f2ef0 100644
--- a/_sass/modules/_footer.scss
+++ b/_sass/modules/_footer.scss
@@ -10,14 +10,14 @@
flex: 1;
flex-direction: column;
font-size: var(--font-size-xx-small);
- gap: 0.8em;
+ gap: var(--space-medium);
letter-spacing: -0.01em;
ul {
align-items: center;
display: flex;
- gap: 0.3em;
+ gap: var(--space-medium);
padding: 0;
li {
@@ -30,7 +30,7 @@
display: flex;
img {
- height: 1.5em;
+ height: 1.75em;
width: auto;
}
diff --git a/assets/images/logo-basecamp.svg b/assets/images/logo-basecamp.svg
index 23acf8c..296fa09 100644
--- a/assets/images/logo-basecamp.svg
+++ b/assets/images/logo-basecamp.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
diff --git a/assets/images/logo-hey.svg b/assets/images/logo-hey.svg
index a0b7849..6ab876c 100644
--- a/assets/images/logo-hey.svg
+++ b/assets/images/logo-hey.svg
@@ -1 +1 @@
-
\ No newline at end of file
+
diff --git a/assets/images/logo-once.svg b/assets/images/logo-once.svg
new file mode 100644
index 0000000..2f3163d
--- /dev/null
+++ b/assets/images/logo-once.svg
@@ -0,0 +1 @@
+
diff --git a/assets/videos/kamal-screencast.vtt b/assets/videos/kamal-screencast.vtt
index 03f5a25..8d2b769 100644
--- a/assets/videos/kamal-screencast.vtt
+++ b/assets/videos/kamal-screencast.vtt
@@ -1226,4 +1226,3 @@ And it is just as easy to deploy this
19:08.400 --> 19:11.720
to your own hardware if you feel up for that.
-
diff --git a/docs/commands/deploy.md b/docs/commands/deploy.md
index b9c6390..b28c896 100644
--- a/docs/commands/deploy.md
+++ b/docs/commands/deploy.md
@@ -6,7 +6,7 @@ title: Deploy
Build and deploy your app to all servers. By default it will build the currently checked out version of the app.
-Kamal will use the kamal-proxy to seamlessly move requests from the old version of the app to new without downtime.
+Kamal will use [kamal-proxy](https://github.com/basecamp/kamal-proxy) to seamlessly move requests from the old version of the app to new without downtime.
The deployment process is:
1. Login into the docker registry locally and on all servers
diff --git a/docs/commands/details.md b/docs/commands/details.md
index e427b15..388f448 100644
--- a/docs/commands/details.md
+++ b/docs/commands/details.md
@@ -4,7 +4,7 @@ title: Details
# kamal details
-Shows details of all your containers
+Shows details of all your containers.
```bash
$ kamal details -q
diff --git a/docs/commands/docs.md b/docs/commands/docs.md
index a430b1e..70022de 100644
--- a/docs/commands/docs.md
+++ b/docs/commands/docs.md
@@ -4,4 +4,4 @@ title: Help
# kamal docs
-Outputs configuration documentation
+Outputs configuration documentation.
diff --git a/docs/commands/init.md b/docs/commands/init.md
index 7614ed6..ef7cb36 100644
--- a/docs/commands/init.md
+++ b/docs/commands/init.md
@@ -10,5 +10,5 @@ Creates the files needed to deploy your application with `kamal`.
$ kamal init
Created configuration file in config/deploy.yml
Created .kamal/secrets file
-Created sample hooks in .kamal/hooks```
+Created sample hooks in .kamal/hooks
```
diff --git a/docs/commands/lock.md b/docs/commands/lock.md
index a94a8bf..9cfefd6 100644
--- a/docs/commands/lock.md
+++ b/docs/commands/lock.md
@@ -6,9 +6,9 @@ title: Lock
Manage deployment locks.
-Commands that are unsafe to run concurrently will take a deploy lock while they run. The lock is the `kamal_lock` directory on the primary server.
+Commands that are unsafe to run concurrently will take a lock while they run. The lock is an atomically created directory in the `.kamal` directory on the primary server.
-You can manage them directly - for example clearing a leftover lock from a failed command or preventing deployments during a maintanence window.
+You can manage them directly — for example clearing a leftover lock from a failed command or preventing deployments during a maintenance window.
```
$ kamal lock
diff --git a/docs/commands/proxy.md b/docs/commands/proxy.md
index 193c15f..0c8ef8e 100644
--- a/docs/commands/proxy.md
+++ b/docs/commands/proxy.md
@@ -20,6 +20,8 @@ Commands:
kamal proxy stop # Stop existing proxy container on servers
```
-When you want to upgrade kamal-proxy, you can call `kamal proxy reboot`. This is going to cause a small outage on each server and will prompt for confirmation.
+When you want to upgrade kamal-proxy, you can call `kamal proxy reboot`. This is going to cause a small outage on each server and will prompt for confirmation.
-You can use a rolling reboot with `kamal proxy reboot --rolling` to avoid restarting on all servers simultaneously. You can also use [pre-proxy-reboot](../hooks/pre-proxy-reboot) and [post-proxy-reboot](../hooks/post-proxy-reboot) hooks to remove and add the servers to upstream load balancers as you reboot them.
+You can use a rolling reboot with `kamal proxy reboot --rolling` to avoid restarting on all servers simultaneously.
+
+You can also use [pre-proxy-reboot](../hooks/pre-proxy-reboot) and [post-proxy-reboot](../hooks/post-proxy-reboot) hooks to remove and add the servers to upstream load balancers as you reboot them.
diff --git a/docs/commands/rollback.md b/docs/commands/rollback.md
index cf68cf0..d6b4edc 100644
--- a/docs/commands/rollback.md
+++ b/docs/commands/rollback.md
@@ -4,7 +4,7 @@ title: kamal rollback
# kamal rollback
-You can rollback a deployment with `kamal rollback`
+You can rollback a deployment with `kamal rollback`.
If you've discovered a bad deploy, you can quickly rollback to a previous image. You can see what old containers are available for rollback by running `kamal app containers -q`. It'll give you a presentation similar to `kamal app details`, but include all the old containers as well.
diff --git a/docs/commands/running-commands-on-servers.md b/docs/commands/running-commands-on-servers.md
index 0abfe75..9abd42e 100644
--- a/docs/commands/running-commands-on-servers.md
+++ b/docs/commands/running-commands-on-servers.md
@@ -4,6 +4,8 @@ title: Running commands on servers
# Running commands on servers
+You can use [aliases](../../configuration/aliases) for common commands.
+
## [Run command on all servers](#run-command-on-all-servers)
```bash
diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md
index 10d8fc9..2bb6b7c 100644
--- a/docs/commands/secrets.md
+++ b/docs/commands/secrets.md
@@ -4,13 +4,6 @@ title: Secrets
# kamal secrets
-```bash
----
-title: Secrets
----
-
-# kamal secrets
-
```bash
$ kamal secrets
Commands:
@@ -18,3 +11,79 @@ Commands:
kamal secrets fetch [SECRETS...] --account=ACCOUNT -a, --adapter=ADAPTER # Fetch secrets from a vault
kamal secrets help [COMMAND] # Describe subcommands or one specific subcommand
```
+
+Use these to read secrets from common password managers (currently 1Password, LastPass and Bitwarden).
+
+The helpers will handle signing in, asking for passwords and efficiently fetching the secrets:
+
+These are designed to be used with [command substitution](https://github.com/bkeepers/dotenv?tab=readme-ov-file#command-substitution) in `.kamal/secrets`
+
+```
+# .kamal/secrets
+
+SECRETS=$(kamal secrets fetch ...)
+
+REGISTRY_PASSWORD=$(kamal secrets extract REGISTRY_PASSWORD $SECRETS)
+DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
+```
+
+## 1Password
+
+Use the adaptor `1password`:
+
+```
+# Fetch from item `MyItem` in the vault `MyVault`
+kamal secrets fetch --adapter 1password --account myaccount --from MyVault/MyItem REGISTRY_PASSWORD DB_PASSWORD
+
+# Fetch from sections of item `MyItem` in the vault `MyVault`
+kamal secrets fetch --adapter 1password --account myaccount --from MyVault/MyItem common/REGISTRY_PASSWORD production/DB_PASSWORD
+
+# Fetch from separate items MyItem, MyItem2
+kamal secrets fetch --adapter 1password --account myaccount --from MyVault MyItem/REGISTRY_PASSWORD MyItem2/DB_PASSWORD
+
+# Fetch from multiple vaults
+kamal secrets fetch --adapter 1password --account myaccount MyVault/MyItem/REGISTRY_PASSWORD MyVault2/MyItem2/DB_PASSWORD
+
+# All three of these will extract the secret
+kamal secrets extract REGISTRY_PASSWORD
+kamal secrets extract MyItem/REGISTRY_PASSWORD
+kamal secrets extract MyVault/MyItem/REGISTRY_PASSWORD
+```
+
+## LastPass
+
+Use the adaptor `lastpass`:
+
+```
+# Fetch passwords
+kamal secrets fetch --adapter lastpass --account email@example.com REGISTRY_PASSWORD DB_PASSWORD
+
+# Fetch passwords from a folder
+kamal secrets fetch --adapter lastpass --account email@example.com --from MyFolder REGISTRY_PASSWORD DB_PASSWORD
+
+# Fetch passwords from multiple folders
+kamal secrets fetch --adapter lastpass --account email@example.com MyFolder/REGISTRY_PASSWORD MyFolder2/DB_PASSWORD
+
+# Extract the secret
+kamal secrets extract REGISTRY_PASSWORD
+kamal secrets extract MyFolder/REGISTRY_PASSWORD
+```
+
+## Bitwarden
+
+Use the adaptor `bitwarden`:
+
+```
+# Fetch passwords
+kamal secrets fetch --adapter bitwarden --account email@example.com REGISTRY_PASSWORD DB_PASSWORD
+
+# Fetch passwords from an item
+kamal secrets fetch --adapter bitwarden --account email@example.com --from MyItem REGISTRY_PASSWORD DB_PASSWORD
+
+# Fetch passwords from multiple items
+kamal secrets fetch --adapter bitwarden --account email@example.com MyItem/REGISTRY_PASSWORD MyItem2/DB_PASSWORD
+
+# Extract the secret
+kamal secrets extract REGISTRY_PASSWORD
+kamal secrets extract MyItem/REGISTRY_PASSWORD
+```
diff --git a/docs/commands/server.md b/docs/commands/server.md
index 72fa8f7..0e4b006 100644
--- a/docs/commands/server.md
+++ b/docs/commands/server.md
@@ -56,4 +56,4 @@ Run an interactive command on the server.
$ kamal server exec --interactive "/bin/bash"
Running '/bin/bash' on 867.53.0.9 interactively...
root@server:~#
-```
\ No newline at end of file
+```
diff --git a/docs/commands/upgrade.md b/docs/commands/upgrade.md
index 5c6e688..2dbe07c 100644
--- a/docs/commands/upgrade.md
+++ b/docs/commands/upgrade.md
@@ -1,14 +1,9 @@
---
-title: Secrets
----
-
-# kamal secrets
-
-```bash
----
title: Upgrade
---
# kamal upgrade
Use `kamal upgrade` to upgrade your app running under Kamal 1.x to Kamal 2.0.
+
+Please read the [Upgrade Guide](../../upgrading/overview) first.
diff --git a/docs/configuration/accessories.md b/docs/configuration/accessories.md
index c8c0923..5fa78ad 100644
--- a/docs/configuration/accessories.md
+++ b/docs/configuration/accessories.md
@@ -4,39 +4,41 @@ 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 ` to boot an accessory.
-See `kamal accessory --help` for more information.
+Run `kamal accessory boot ` to boot an accessory. See `kamal accessory --help` for more information.
## [Configuring accessories](#configuring-accessories)
-First define the accessory in the `accessories`
+First define the accessory in the `accessories`:
+
```yaml
accessories:
mysql:
```
+
## [Service name](#service-name)
-This is used in the service label and defaults to `-`
-where `` is the main service name from the root configuration
+This is used in the service label and defaults to `-` where `` is the main service name from the root configuration:
+
```yaml
service: mysql
```
+
## [Image](#image)
-The Docker image to use, prefix with a registry if not using Docker hub
+The Docker image to use, prefix with a registry if not using Docker hub:
+
```yaml
image: mysql:8.0
```
+
## [Accessory hosts](#accessory-hosts)
-Specify one of `host`, `hosts` or `roles`
+Specify one of `host`, `hosts` or `roles`:
+
```yaml
host: mysql-db1
hosts:
@@ -45,63 +47,76 @@ Specify one of `host`, `hosts` or `roles`
roles:
- mysql
```
+
## [Custom command](#custom-command)
-You can set a custom command to run in the container, if you do not want to use the default
+You can set a custom command to run in the container, if you do not want to use the default:
+
```yaml
cmd: "bin/mysqld"
```
+
## [Port mappings](#port-mappings)
-See https://docs.docker.com/network/, especially note the warning about the security
-implications of exposing ports publicly.
+See https://docs.docker.com/network/, especially note the warning about the security implications of exposing ports publicly.
+
```yaml
port: "127.0.0.1:3306:3306"
```
+
## [Labels](#labels)
+
```yaml
labels:
app: myapp
```
+
## [Options](#options)
-These are passed to the Docker run command in the form `--`
+
+These are passed to the Docker run command in the form `--`:
+
```yaml
options:
restart: always
cpus: 2
```
+
## [Environment variables](#environment-variables)
-See [Environment variables](../environment-variables) for more information
+
+See [Environment variables](../environment-variables) for more information:
+
```yaml
env:
...
```
+
## [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.
ERB files will be evaluated before being copied.
+
```yaml
files:
- config/my.cnf.erb:/etc/mysql/my.cnf
- config/myoptions.cnf:/etc/mysql/myoptions.cnf
```
+
## [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:
- mysql-logs:/var/log/mysql
```
+
## [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:
- /path/to/mysql-logs:/var/log/mysql
diff --git a/docs/configuration/aliases.md b/docs/configuration/aliases.md
index a85522a..d95d763 100644
--- a/docs/configuration/aliases.md
+++ b/docs/configuration/aliases.md
@@ -4,7 +4,6 @@ title: Aliases
# Aliases
-
Aliases are shortcuts for Kamal commands.
For example, for a Rails app, you might open a console with:
@@ -14,20 +13,23 @@ kamal app exec -i -r console "rails console"
```
By defining an alias, like this:
+
```yaml
aliases:
console: app exec -r console -i "rails console"
```
+
You can now open the console with:
+
```shell
kamal console
```
## [Configuring aliases](#configuring-aliases)
-Aliases are defined in the root config under the alias key
+Aliases are defined in the root config under the alias key.
-Each alias is named and can only contain lowercase letters, numbers, dashes and underscores.
+Each alias is named and can only contain lowercase letters, numbers, dashes and underscores:
```yaml
aliases:
diff --git a/docs/configuration/booting.md b/docs/configuration/booting.md
index 8825641..fd916a7 100644
--- a/docs/configuration/booting.md
+++ b/docs/configuration/booting.md
@@ -4,22 +4,24 @@ title: Booting
# Booting
-
When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
Kamal’s default is to boot new containers on all hosts in parallel. But you can control this with the boot configuration.
## [Fixed group sizes](#fixed-group-sizes)
-Here we boot 2 hosts at a time with a 10 second gap between each group.
+Here we boot 2 hosts at a time with a 10 second gap between each group:
+
```yaml
boot:
limit: 2
wait: 10
```
+
## [Percentage of hosts](#percentage-of-hosts)
-Here we boot 25% of the hosts at a time with a 2 second gap between each group.
+Here we boot 25% of the hosts at a time with a 2 second gap between each group:
+
```yaml
boot:
limit: 25%
diff --git a/docs/configuration/builder-examples.md b/docs/configuration/builder-examples.md
index 99b89cf..fc2a63f 100644
--- a/docs/configuration/builder-examples.md
+++ b/docs/configuration/builder-examples.md
@@ -22,7 +22,7 @@ Kamal will use the remote to build when deploying from an ARM64 machine, or buil
## [Using remote builder for single-arch](#using-remote-builder-for-native-multi-arch)
-You can also build a multi-arch image. If a remote is set, Kamal will build the deployment arch locally and the other arch remotely.
+You can also build a multi-arch image. If a remote is set, Kamal will build the arch matching your deployment server locally and the other arch remotely.
So if you're developing on ARM64 (like Apple Silicon), it will build the ARM64 arch locally and the AMD64 arch remotely.
@@ -64,7 +64,7 @@ builder:
## [Using multistage builder cache](#using-multistage-builder-cache)
-Docker multistage build cache can singlehandedly speed up your builds by a lot. Currently Kamal only supports using the GHA cache or the Registry cache:
+Docker multistage build cache can speed up your builds. Currently Kamal only supports using the GHA cache or the Registry cache:
```yaml
# Using GHA cache
@@ -111,9 +111,17 @@ For further insights into build cache optimization, check out documentation on D
## [Using build secrets for new images](#using-build-secrets-for-new-images)
-Some images need a secret passed in during build time, like a GITHUB_TOKEN, to give access to private gem repositories. This can be done by setting the secret in .kamal/secrets, then referencing it in the builder configuration:
+Some images need a secret passed in during build time, like a GITHUB_TOKEN, to give access to private gem repositories. This can be done by setting the secret in `.kamal/secrets`, then referencing it in the builder configuration:
+
+```bash
+# .kamal/secrets
+
+GITHUB_TOKEN=$(gh config get -h github.com oauth_token)
+```
```yaml
+# config/deploy.yml
+
builder:
secrets:
- GITHUB_TOKEN
diff --git a/docs/configuration/builders.md b/docs/configuration/builders.md
index f109c08..f81a04e 100644
--- a/docs/configuration/builders.md
+++ b/docs/configuration/builders.md
@@ -4,85 +4,95 @@ title: Builder
# Builder
+The builder configuration controls how the application is built with `docker build`.
-The builder configuration controls how the application is built with `docker build`
-
-If no configuration is specified, Kamal will:
-1. Create a buildx context called `kamal-local-docker-container`, using the docker-container driver
-2. Use `docker build` to build a multiarch image for linux/amd64,linux/arm64 with that context
-
-See [Builder examples](/docs/configuration/builder-examples/) for more information
+See [Builder examples](/docs/configuration/builder-examples/) for more information.
## [Builder options](#builder-options)
Options go under the builder key in the root configuration.
+
```yaml
builder:
```
+
## [Arch](#arch)
-The architectures to build for - you can set an array or just a single value.
+The architectures to build for — you can set an array or just a single value.
+
+Allowed values are `amd64` and `arm64`:
-Allowed values are `amd64` and `arm64`
```yaml
arch:
- amd64
```
+
## [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:
-Defaults to true
```yaml
local: true
```
+
## [Builder cache](#builder-cache)
-The type must be either 'gha' or 'registry'
+The type must be either 'gha' or 'registry'.
+
+The image is only used for registry cache. Not compatible with the docker driver:
-The image is only used for registry cache. Not compatible with the docker driver
```yaml
cache:
type: registry
options: mode=max
image: kamal-app-build-cache
```
+
## [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.
+
```yaml
context: .
```
+
## [Dockerfile](#dockerfile)
-The Dockerfile to use for building, defaults to `Dockerfile`
+The Dockerfile to use for building, defaults to `Dockerfile`:
+
```yaml
dockerfile: Dockerfile.production
```
+
## [Build target](#build-target)
-If not set, then the default target is used
+If not set, then the default target is used:
+
```yaml
target: production
```
-## [Build Arguments](#build-arguments)
-Any additional build arguments, passed to `docker build` with `--build-arg =`
+## [Build arguments](#build-arguments)
+
+Any additional build arguments, passed to `docker build` with `--build-arg =`:
+
```yaml
args:
ENVIRONMENT: production
```
+
## [Referencing build arguments](#referencing-build-arguments)
```shell
@@ -92,14 +102,15 @@ FROM ruby:$RUBY_VERSION-slim as base
## [Build secrets](#build-secrets)
-Values are read from the .kamal/secrets.
+Values are read from .kamal/secrets.
```yaml
secrets:
- SECRET1
- SECRET2
```
-## [Referencing Build Secrets](#referencing-build-secrets)
+
+## [Referencing build secrets](#referencing-build-secrets)
```shell
# Copy Gemfiles
@@ -113,16 +124,18 @@ RUN --mount=type=secret,id=GITHUB_TOKEN \
rm -rf /usr/local/bundle/cache
```
-
## [SSH](#ssh)
-SSH agent socket or keys to expose to the build
+SSH agent socket or keys to expose to the build:
+
```yaml
ssh: default=$SSH_AUTH_SOCK
```
+
## [Driver](#driver)
-The build driver to use, defaults to `docker-container`
+The build driver to use, defaults to `docker-container`:
+
```yaml
driver: docker
```
diff --git a/docs/configuration/docker-registry.md b/docs/configuration/docker-registry.md
index aacdd37..2a8eef4 100644
--- a/docs/configuration/docker-registry.md
+++ b/docs/configuration/docker-registry.md
@@ -4,11 +4,9 @@ title: Registry
# Registry
-
The default registry is Docker Hub, but you can change it using registry/server:
-A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret
-in the local environment.
+A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret in the local environment.
```yaml
registry:
@@ -18,9 +16,10 @@ registry:
password:
- DOCKER_REGISTRY_TOKEN
```
+
## [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 12hrs. In order to not have 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 12hrs. In order to not have 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:
@@ -28,21 +27,20 @@ registry:
username: AWS
password: <%= %x(aws ecr get-login-password) %>
```
+
## [Using GCP Artifact Registry as the container registry](#using-gcp-artifact-registry-as-the-container-registry)
-To sign into Artifact Registry, you would 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 a roles/artifactregistry.writer role should be sufficient.
+
+To sign into Artifact Registry, you would 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 a 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:
```shell
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 env variable as password along with _json_key_base64 as username.
-Here’s the final configuration:
+Use the env variable as password along with _json_key_base64 as username. Here’s the final configuration:
```yaml
registry:
@@ -51,9 +49,11 @@ registry:
password:
- KAMAL_REGISTRY_PASSWORD
```
+
## [Validating the configuration](#validating-the-configuration)
You can validate the configuration by running:
+
```shell
kamal registry login
```
diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md
index 0d6f1cf..a3bde24 100644
--- a/docs/configuration/environment-variables.md
+++ b/docs/configuration/environment-variables.md
@@ -4,39 +4,50 @@ 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)
Environment variables can be set directly in the configuration file.
These are passed to the docker run command when deploying.
+
```yaml
env:
DATABASE_HOST: mysql-db1
DATABASE_PORT: 3306
```
-## [Using .kamal/secrets file to load required environment variables](#using-.kamal/secrets-file-to-load-required-environment-variables)
-Kamal uses dotenv to automatically load environment variables set in the .kamal/secrets file.
+## [Secrets](#secrets)
+
+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-` if it exists.
-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.
+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.
```
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
RAILS_MASTER_KEY=$(cat config/master.key)
```
+You can also use [secret helpers](../commands/secrets) for some common password managers.
+
+```
+SECRETS=$(kamal secrets fetch ...)
+
+REGISTRY_PASSWORD=$(kamal secrets extract REGISTRY_PASSWORD $SECRETS)
+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:
clear:
@@ -44,14 +55,15 @@ env:
secret:
- DB_PASSWORD
```
+
## [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).
The env variables can be specified with secret and clear values as explained above.
+
```yaml
env:
tags:
@@ -63,7 +75,9 @@ env:
secret:
- MYSQL_PASSWORD
```
+
## [Example configuration](#example-configuration)
+
```yaml
env:
clear:
diff --git a/docs/configuration/index.md b/docs/configuration/index.md
index 1d462f0..0ee8e04 100644
--- a/docs/configuration/index.md
+++ b/docs/configuration/index.md
@@ -1,5 +1,5 @@
---
search: false
redirect_to:
- - /docs/configuration/configuration-overview/
+ - /docs/configuration/overview/
---
diff --git a/docs/configuration/logging.md b/docs/configuration/logging.md
index 67d9bd9..4d36847 100644
--- a/docs/configuration/logging.md
+++ b/docs/configuration/logging.md
@@ -4,7 +4,6 @@ title: Custom logging configuration
# Custom logging configuration
-
Set these to control the Docker logging driver and options.
## [Logging settings](#logging-settings)
@@ -12,18 +11,23 @@ Set these to control the Docker logging driver and options.
These go under the logging key in the configuration file.
This can be specified in the root level or for a specific role.
+
```yaml
logging:
```
+
## [Driver](#driver)
-The logging driver to use, passed to Docker via `--log-driver`
+The logging driver to use, passed to Docker via `--log-driver`:
+
```yaml
driver: json-file
```
+
## [Options](#options)
-Any logging options to pass to the driver, passed to Docker via `--log-opt`
+Any logging options to pass to the driver, passed to Docker via `--log-opt`:
+
```yaml
options:
max-size: 100m
diff --git a/docs/configuration/configuration-overview.md b/docs/configuration/overview.md
similarity index 61%
rename from docs/configuration/configuration-overview.md
rename to docs/configuration/overview.md
index e58ebdf..a598fd2 100644
--- a/docs/configuration/configuration-overview.md
+++ b/docs/configuration/overview.md
@@ -4,202 +4,246 @@ title: Kamal Configuration
# Kamal Configuration
-
-Configuration is read from the `config/deploy.yml`
-
+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 use 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 use 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)
+
This is a required value. It is used as the container name prefix.
+
```yaml
service: myapp
```
+
## [The Docker image name](#the-docker-image-name)
The image will be pushed to the configured registry.
+
```yaml
image: my-image
```
+
## [Labels](#labels)
-Additional labels to add to the container
+Additional labels to add to the container:
+
```yaml
labels:
my-label: my-value
```
-## [Additional volumes to mount into the container](#additional-volumes-to-mount-into-the-container)
+
+## [Volumes](#volumes)
+
+Additional volumes to mount into the container:
+
```yaml
volumes:
- /path/on/host:/path/in/container:ro
```
+
## [Registry](#registry)
-The Docker registry configuration, see [Docker Registry](../docker-registry)
+The Docker registry configuration, see [Docker Registry](../docker-registry):
+
```yaml
registry:
...
```
+
## [Servers](#servers)
-The servers to deploy to, optionally with custom roles, see [Servers](../servers)
+The servers to deploy to, optionally with custom roles, see [Servers](../servers):
+
```yaml
servers:
...
```
+
## [Environment variables](#environment-variables)
-See [Environment variables](../environment-variables)
+See [Environment variables](../environment-variables):
+
```yaml
env:
...
```
-## [Asset Bridging](#asset-bridging)
-Used for asset bridging across deployments, default to `nil`
+## [Asset path](#asset-path)
+
+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:
+
```yaml
asset_path: /path/to/assets
```
-## [Path to hooks, defaults to `.kamal/hooks`](#path-to-hooks,-defaults-to-`.kamal/hooks`)
-See [Hooks](/docs/hooks) for more information
+
+## [Hooks path](#hooks-path)
+
+Path to hooks, defaults to `.kamal/hooks`. See [Hooks](/docs/hooks) for more information:
+
```yaml
hooks_path: /user_home/kamal/hooks
```
+
## [Require destinations](#require-destinations)
-Whether deployments require a destination to be specified, defaults to `false`
+Whether deployments require a destination to be specified, defaults to `false`:
+
```yaml
require_destination: true
```
-## [The primary role](#the-primary-role)
-This defaults to `web`, but if you have no web role, you can change this
+## [Primary role](#primary-role)
+
+This defaults to `web`, but if you have no web role, you can change this:
+
```yaml
primary_role: workers
```
+
## [Allowing empty roles](#allowing-empty-roles)
-Whether roles with no servers are allowed. Defaults to `false`.
+Whether roles with no servers are allowed. Defaults to `false`:
+
```yaml
allow_empty_roles: false
```
+
## [Retain containers](#retain-containers)
-How many old containers and images we retain, defaults to 5
+How many old containers and images we retain, defaults to 5:
+
```yaml
retain_containers: 3
```
+
## [Minimum version](#minimum-version)
-The minimum version of Kamal required to deploy this configuration, defaults to nil
+The minimum version of Kamal required to deploy this configuration, defaults to nil:
+
```yaml
minimum_version: 1.3.0
```
+
## [Readiness delay](#readiness-delay)
-Seconds to wait for a container to boot after is running, default 7
+Seconds to wait for a container to boot after is running, default 7.
+
+This only applies to containers that do not run a proxy or specify a healthcheck:
-This only applies to containers that do not run a proxy or specify a healthcheck
```yaml
readiness_delay: 4
```
+
## [Deploy timeout](#deploy-timeout)
-How long to wait for a container to become ready, default 30
+How long to wait for a container to become ready, default 30:
+
```yaml
deploy_timeout: 10
```
+
## [Drain timeout](#drain-timeout)
-How long to wait for a containers to drain, default 30
+How long to wait for a containers to drain, default 30:
+
```yaml
drain_timeout: 10
```
+
## [Run directory](#run-directory)
-Directory to store kamal runtime files in on the host, default `.kamal`
+Directory to store kamal runtime files in on the host, default `.kamal`.
+
```yaml
run_directory: /etc/kamal
```
+
## [SSH options](#ssh-options)
-See [SSH](../ssh)
+See [SSH](../ssh):
+
```yaml
ssh:
...
```
+
## [Builder options](#builder-options)
-See [Builders](../builders)
+See [Builders](../builders):
+
```yaml
builder:
...
```
+
## [Accessories](#accessories)
-Additionals services to run in Docker, see [Accessories](../accessories)
+Additionals services to run in Docker, see [Accessories](../accessories):
+
```yaml
accessories:
...
```
+
## [Proxy](#proxy)
-Configuration for kamal-proxy, see [Proxy](../proxy)
+Configuration for kamal-proxy, see [Proxy](../proxy):
+
```yaml
proxy:
...
```
+
## [SSHKit](#sshkit)
-See [SSHKit](../sshkit)
+See [SSHKit](../sshkit):
+
```yaml
sshkit:
...
```
+
## [Boot options](#boot-options)
-See [Booting](../booting)
+See [Booting](../booting):
+
```yaml
boot:
...
```
+
## [Logging](#logging)
-Docker logging configuration, see [Logging](../logging)
+Docker logging configuration, see [Logging](../logging):
+
```yaml
logging:
...
```
+
## [Aliases](#aliases)
-Alias configuration, see [Aliases](../aliases)
+Alias configuration, see [Aliases](../aliases):
+
```yaml
aliases:
...
diff --git a/docs/configuration/proxy.md b/docs/configuration/proxy.md
index cbbe7ef..295a859 100644
--- a/docs/configuration/proxy.md
+++ b/docs/configuration/proxy.md
@@ -4,76 +4,81 @@ title: Proxy
# Proxy
+Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to provide gapless deployments. It runs on ports 80 and 443 and forwards requests to the application container.
-Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to provide
-gapless deployments. It runs on ports 80 and 443 and forwards requests to the
-application container.
+The proxy is configured in the root configuration under `proxy`. These are options that are set when deploying the application, not when booting the proxy
-The proxy is configured in the root configuration under `proxy`. These are
-options that are set when deploying the application, not when booting the proxy
+They are application specific, so are not shared when multiple applications run on the same proxy.
+
+The proxy is enabled by default on the primary role, but can be disabled by setting `proxy: false`.
+
+It is disabled by default on all other roles, but can be enabled by setting `proxy: true`, or providing a proxy configuration.
-They are application specific, so are not shared when multiple applications
-run on the same proxy.
```yaml
proxy:
```
+
## [Host](#host)
-The hosts that will be used to serve the app. The proxy will only route requests
-to this host to your app.
+The hosts that will be used to serve the app. The proxy will only route requests to this host to your app.
+
+If no hosts are set, then all requests will be forwarded, except for matching requests for other apps deployed on that server that do have a host set.
-If no hosts are set, then all requests will be forwarded, except for matching
-requests for other apps deployed on that server that do have a host set.
```yaml
host: foo.example.com
```
+
## [App port](#app-port)
-The port the application container is exposed on
+The port the application container is exposed on.
+
+Defaults to 80:
-Defaults to 80
```yaml
app_port: 3000
```
+
## [SSL](#ssl)
kamal-proxy can provide automatic HTTPS for your application via Let's Encrypt.
-This requires that we are deploying to a one server and the host option is set.
-The host value must point to the server we are deploying to and port 443 must be
-open for the Let's Encrypt challenge to succeed.
+This requires that we are deploying to a one server and the host option is set. The host value must point to the server we are deploying to and port 443 must be open for the Let's Encrypt challenge to succeed.
+
+Defaults to false:
-Defaults to false
```yaml
ssl: true
```
+
## [Response timeout](#response-timeout)
-How long to wait for requests to complete before timing out, defaults to 30 seconds
+How long to wait for requests to complete before timing out, defaults to 30 seconds:
+
```yaml
- response_timeout: 10s
+ response_timeout: 10
```
+
## [Healthcheck](#healthcheck)
-When deploying, the proxy will by default hit /up once every second until we hit
-the deploy timeout, with a 5 second timeout for each request.
+When deploying, the proxy will by default hit /up once every second until we hit the deploy timeout, with a 5 second timeout for each request.
Once the app is up, the proxy will stop hitting the healthcheck endpoint.
+
```yaml
healthcheck:
interval: 3
path: /health
timeout: 3
```
+
## [Buffering](#buffering)
-Whether to buffer request and response bodies in the proxy
+Whether to buffer request and response bodies in the proxy.
+
+By default buffering is enabled with a max request body size of 1GB and no limit for response size.
-By default buffering is enabled with a max request body size of 1GB and no limit
-for response size.
+You can also set the memory limit for buffering, which defaults to 1MB, anything larger than that is written to disk.
-You can also set the memory limit for buffering, which defaults to 1MB, anything
-larger than that is written to disk.
```yaml
buffering:
requests: true
@@ -82,11 +87,11 @@ larger than that is written to disk.
max_response_body: 0
memory: 2_000_000
```
+
## [Logging](#logging)
-Configure request logging for the proxy
-You can specify request and response headers to log.
-By default, Cache-Control, Last-Modified and User-Agent request headers are logged
+Configure request logging for the proxy. You can specify request and response headers to log. By default, Cache-Control, Last-Modified and User-Agent request headers are logged:
+
```yaml
logging:
request_headers:
@@ -96,14 +101,15 @@ By default, Cache-Control, Last-Modified and User-Agent request headers are logg
- X-Request-ID
- X-Request-Start
```
+
## [Forward headers](#forward-headers)
-Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers (defaults to false)
+Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers.
If you are behind a trusted proxy, you can set this to true to forward the headers.
-By default kamal-proxy will not forward the headers the ssl option is set to true, and
-will forward them if it is set to false.
+By default kamal-proxy will not forward the headers the ssl option is set to true, and will forward them if it is set to false.
+
```yaml
forward_headers: true
```
diff --git a/docs/configuration/roles.md b/docs/configuration/roles.md
index 41bc34c..1aca44f 100644
--- a/docs/configuration/roles.md
+++ b/docs/configuration/roles.md
@@ -4,52 +4,56 @@ title: Roles
# Roles
+Roles are used to configure different types of servers in the deployment. The most common use for this is to run a web servers and job servers.
-Roles are used to configure different types of servers in the deployment.
-The most common use for this is to run a web servers and job servers.
-
-Kamal expects there to be a `web` role, unless you set a different `primary_role`
-in the root configuration.
+Kamal expects there to be a `web` role, unless you set a different `primary_role` in the root configuration.
## [Role configuration](#role-configuration)
-Roles are specified under the servers key
+Roles are specified under the servers key:
+
```yaml
servers:
```
-## [Simple role configuration](#simple-role-configuration)
+## [Simple role configuration](#simple-role-configuration)
This can be a list of hosts, if you don't need custom configuration for the role.
-You can set tags on the hosts for custom env variables (see [Environment variables](../environment-variables))
+You can set tags on the hosts for custom env variables (see [Environment variables](../environment-variables)):
+
```yaml
web:
- 172.1.0.1
- 172.1.0.2: experiment1
- 172.1.0.2: [ experiment1, experiment2 ]
```
+
## [Custom role configuration](#custom-role-configuration)
-When there are other options to set, the list of hosts goes under the `hosts` key
+When there are other options to set, the list of hosts goes under the `hosts` key.
+
+By default only the primary role uses a proxy.
+
+For other roles, you can set it to `proxy: true` enable it and inherit the root proxy configuration or provide a map of options to override the root configuration.
-By default only the primary role uses a proxy, but you can set `proxy` to change
-it.
+For the primary role, you can set `proxy: false` to disable the proxy.
+
+You can also set a custom cmd to run in the container, and overwrite other settings from the root configuration.
-You can also set a custom cmd to run in the container, and overwrite other settings
-from the root configuration.
```yaml
workers:
hosts:
- 172.1.0.3
- 172.1.0.4: experiment1
- proxy: true
cmd: "bin/jobs"
options:
memory: 2g
cpus: 4
logging:
...
+ proxy:
+ ...
labels:
my-label: workers
env:
diff --git a/docs/configuration/servers.md b/docs/configuration/servers.md
index b2a0643..da220dd 100644
--- a/docs/configuration/servers.md
+++ b/docs/configuration/servers.md
@@ -4,29 +4,32 @@ title: Servers
# Servers
-
Servers are split into different roles, with each role having its own configuration.
-For simpler deployments though where all servers are identical, you can just specify a list of servers
-They will be implicitly assigned to the `web` role.
+For simpler deployments though where all servers are identical, you can just specify a list of servers. They will be implicitly assigned to the `web` role.
+
```yaml
servers:
- 172.0.0.1
- 172.0.0.2
- 172.0.0.3
```
+
## [Tagging servers](#tagging-servers)
Servers can be tagged, with the tags used to add custom env variables (see [Environment variables](../environment-variables)).
+
```yaml
servers:
- 172.0.0.1
- 172.0.0.2: experiments
- 172.0.0.3: [ experiments, three ]
```
+
## [Roles](#roles)
-For more complex deployments (e.g. if you are running job hosts), you can specify roles, and configure each separately (see [Roles](../roles))
+For more complex deployments (e.g. if you are running job hosts), you can specify roles, and configure each separately (see [Roles](../roles)):
+
```yaml
servers:
web:
diff --git a/docs/configuration/ssh.md b/docs/configuration/ssh.md
index 0faa7ed..8082565 100644
--- a/docs/configuration/ssh.md
+++ b/docs/configuration/ssh.md
@@ -4,9 +4,7 @@ title: SSH configuration
# SSH configuration
-
-Kamal uses SSH to connect run commands on your hosts.
-By default it will attempt to connect to the root user on port 22
+Kamal uses SSH to connect run commands on your hosts. By default it will attempt to connect to the root user on port 22.
If you are using non-root user, you may need to bootstrap your servers manually, before using them with Kamal. On Ubuntu, you’d do:
@@ -17,65 +15,74 @@ sudo apt install -y docker.io curl git
sudo usermod -a -G docker app
```
-
## [SSH options](#ssh-options)
The options are specified under the ssh key in the configuration file.
+
```yaml
ssh:
```
+
## [The SSH user](#the-ssh-user)
-Defaults to `root`
+Defaults to `root`:
```yaml
user: app
```
+
## [The SSH port](#the-ssh-port)
-Defaults to 22
+Defaults to 22:
+
```yaml
port: "2222"
```
+
## [Proxy host](#proxy-host)
-Specified in the form or @
+Specified in the form or @:
+
```yaml
proxy: root@proxy-host
```
+
## [Proxy command](#proxy-command)
-A custom proxy command, required for older versions of SSH
+A custom proxy command, required for older versions of SSH:
+
```yaml
proxy_command: "ssh -W %h:%p user@proxy"
```
+
## [Log level](#log-level)
-Defaults to `fatal`. Set this to debug if you are having
- SSH connection issues.
+Defaults to `fatal`. Set this to debug if you are having SSH connection issues.
+
```yaml
log_level: debug
```
-## [Keys Only](#keys-only)
-Set to true to use only private keys from keys and key_data parameters,
-even if ssh-agent offers more identities. This option is intended for
-situations where ssh-agent offers many different identites or you have
-a need to overwrite all identites and force a single one.
+## [Keys only](#keys-only)
+
+Set to true to use only private keys from keys and key_data parameters, even if ssh-agent offers more identities. This option is intended for situations where ssh-agent offers many different identities or you have a need to overwrite all identities and force a single one.
+
```yaml
keys_only: false
```
+
## [Keys](#keys)
-An array of file names of private keys to use for publickey
-and hostbased authentication
+An array of file names of private keys to use for publickey and hostbased authentication:
+
```yaml
keys: [ "~/.ssh/id.pem" ]
```
-## [Key Data](#key-data)
-An array of strings, with each element of the array being
-a raw private key in PEM format.
+## [Key data](#key-data)
+
+An array of strings, with each element of the array being a raw private key in PEM format.
+
```yaml
key_data: [ "-----BEGIN OPENSSH PRIVATE KEY-----" ]
```
diff --git a/docs/configuration/sshkit.md b/docs/configuration/sshkit.md
index f0b38a0..f006de7 100644
--- a/docs/configuration/sshkit.md
+++ b/docs/configuration/sshkit.md
@@ -4,29 +4,30 @@ title: SSHKit
# SSHKit
-
[SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal.
-The default settings should be sufficient for most use cases, but
-when connecting to a large number of hosts you may need to adjust
+The default settings should be sufficient for most use cases, but when connecting to a large number of hosts you may need to adjust.
## [SSHKit options](#sshkit-options)
The options are specified under the sshkit key in the configuration file.
+
```yaml
sshkit:
```
+
## [Max concurrent starts](#max-concurrent-starts)
-Creating SSH connections concurrently can be an issue when deploying to many servers.
-By default Kamal will limit concurrent connection starts to 30 at a time.
+Creating SSH connections concurrently can be an issue when deploying to many servers. By default Kamal will limit concurrent connection starts to 30 at a time.
+
```yaml
max_concurrent_starts: 10
```
+
## [Pool idle timeout](#pool-idle-timeout)
-Kamal sets a long idle timeout of 900 seconds on connections to try to avoid
-re-connection storms after an idle period, like building an image or waiting for CI.
+Kamal sets a long idle timeout of 900 seconds on connections to try to avoid re-connection storms after an idle period, like building an image or waiting for CI.
+
```yaml
pool_idle_timeout: 300
```
diff --git a/docs/hooks/docker-setup.md b/docs/hooks/docker-setup.md
index 4aa48bc..5b953d4 100644
--- a/docs/hooks/docker-setup.md
+++ b/docs/hooks/docker-setup.md
@@ -1,7 +1,7 @@
---
-title: pre-connect
+title: docker-setup
---
-# docker-setup hook
+# Hooks: docker-setup
Run once Docker is installed on a server but before taking any application-specific actions. Designed for performing any necessary configuration of Docker itself.
diff --git a/docs/hooks/index.md b/docs/hooks/index.md
index 0befbec..46b0884 100644
--- a/docs/hooks/index.md
+++ b/docs/hooks/index.md
@@ -1,5 +1,5 @@
---
search: false
redirect_to:
- - /docs/hooks/hooks-overview/
+ - /docs/hooks/overview/
---
diff --git a/docs/hooks/hooks-overview.md b/docs/hooks/overview.md
similarity index 100%
rename from docs/hooks/hooks-overview.md
rename to docs/hooks/overview.md
diff --git a/docs/hooks/post-deploy.md b/docs/hooks/post-deploy.md
index 5902453..b18649e 100644
--- a/docs/hooks/post-deploy.md
+++ b/docs/hooks/post-deploy.md
@@ -2,7 +2,7 @@
title: post-deploy
---
-# post-deploy hook
+# Hooks: post-deploy
Run after a deploy, redeploy or rollback. This hook is also passed a `KAMAL_RUNTIME` env variable set to the total seconds the deploy took.
diff --git a/docs/hooks/post-proxy-reboot.md b/docs/hooks/post-proxy-reboot.md
index 0af88be..5e8dd82 100644
--- a/docs/hooks/post-proxy-reboot.md
+++ b/docs/hooks/post-proxy-reboot.md
@@ -2,6 +2,6 @@
title: post-proxy-reboot
---
-# post-proxy-reboot hook
+# Hooks: post-proxy-reboot
Runs after rebooting the kamal-proxy container, see [pre-proxy-reboot](../pre-proxy-reboot) for details.
diff --git a/docs/hooks/pre-build.md b/docs/hooks/pre-build.md
index e8162e4..bfcf8cc 100644
--- a/docs/hooks/pre-build.md
+++ b/docs/hooks/pre-build.md
@@ -2,6 +2,6 @@
title: pre-build
---
-# pre-build hook
+# Hooks: pre-build
Used for pre-build checks, e.g. there are no uncommitted changes or that CI has passed.
diff --git a/docs/hooks/pre-connect.md b/docs/hooks/pre-connect.md
index 78202b6..71ae464 100644
--- a/docs/hooks/pre-connect.md
+++ b/docs/hooks/pre-connect.md
@@ -2,6 +2,6 @@
title: pre-connect
---
-# pre-connect hook
+# Hooks: pre-connect
Runs before taking the deploy lock. For anything that need to run before connecting to remote hosts, e.g. DNS warming, checking if you are on the VPN.
diff --git a/docs/hooks/pre-deploy.md b/docs/hooks/pre-deploy.md
index d5ad41f..86b810c 100644
--- a/docs/hooks/pre-deploy.md
+++ b/docs/hooks/pre-deploy.md
@@ -2,6 +2,6 @@
title: pre-deploy
---
-# pre-deploy hook
+# Hooks: pre-deploy
For final checks before deploying, e.g. checking CI completed.
diff --git a/docs/hooks/pre-proxy-reboot.md b/docs/hooks/pre-proxy-reboot.md
index d607a6f..7ea378b 100644
--- a/docs/hooks/pre-proxy-reboot.md
+++ b/docs/hooks/pre-proxy-reboot.md
@@ -2,7 +2,7 @@
title: pre-proxy-reboot
---
-# pre-proxy-reboot hook
+# Hooks: pre-proxy-reboot
Run before rebooting the kamal-proxy container, when you call `kamal proxy reboot`.
diff --git a/docs/index.md b/docs/index.md
index 18e51e7..b327daf 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,4 +1,5 @@
---
+search: false
redirect_to:
- /docs/installation/
---
diff --git a/docs/upgrading/configuration-changes.md b/docs/upgrading/configuration-changes.md
new file mode 100644
index 0000000..77c7ea5
--- /dev/null
+++ b/docs/upgrading/configuration-changes.md
@@ -0,0 +1,114 @@
+---
+title: Configuration changes
+---
+
+# Configuration changes
+
+## [Builder](#builder)
+
+The [builder configuration](../configuration/builders) has been simplified.
+
+### Arch
+
+You must specify the architecture(s) you are building for:
+
+```yaml
+# single arch
+builder:
+ arch: amd64
+
+# multi arch
+builder:
+ arch:
+ - amd64
+ - arm64
+```
+
+### Remote builders
+
+Set the remote directly with the remote option. By default it will only be used if the arch you are building doesn't match the local machine:
+
+```yaml
+builder:
+ arch: amd64
+ remote: ssh://docker@docker-builder
+```
+
+You can force Kamal to only use the remote builder, by setting `local: false`:
+
+```yaml
+builder:
+ arch: amd64
+ local: false
+ remote: ssh://docker@docker-builder
+```
+
+### Driver
+
+Kamal will now always use the docker container (link) driver by default. You can set the driver yourself to change this:
+
+```yaml
+builder:
+ driver: docker
+```
+
+The docker driver has limited capabilities — it doesn't support build caching or multiarch images.
+
+## [Traefik → Proxy](#traefik-to-proxy)
+
+The `traefik` configuration is no longer valid. Instead you can configure kamal-proxy under [proxy](../../configuration/proxy).
+
+If you were using custom Traefik labels or args, see the proxy configuration whether you can convert them.
+
+kamal-proxy supports common requirements such as buffering, max request/response sizes, and forwarding headers, but it is not the full breadth of everything Traefik can do.
+
+If you don't see something you need, you can raise an issue and we'll look into it, but we don't promise to support everything — you might need to run Traefik or another proxy elsewhere in your stack to achieve what you want.
+
+## [Healthchecks](#healthchecks)
+
+The healthcheck section has been removed.
+
+### Proxy roles
+
+For roles running with a proxy, the healthchecks are performed externally by kamal-proxy, not via internal Docker healthchecks. You can configure the them under [proxy/healthcheck](../../configuration/proxy#healthcheck).
+
+```
+proxy:
+ healthcheck:
+ path: /health
+ interval: 2
+ timeout: 2
+```
+
+### Non-proxy roles
+
+For roles that do not run the proxy, you can set a custom docker healthcheck via the [options](../../configuration/roles#custom-role-configuration).
+
+```yaml
+servers:
+ web:
+ ...
+ jobs:
+ options:
+ health-cmd: bin/jobs-healthy
+```
+
+For those containers, Kamal will wait for the `healthy` status if they have a healthcheck or `running` if they don't.
+
+You can set a `readiness_delay` which is used when we see the `running` status. We'll wait that long and confirm the container is still running before continuing.
+
+### All roles
+
+There are two timeouts you can set at the root of the config that are used across all roles whether they use a proxy or not.
+
+```yaml
+# how long to wait for new containers to boot
+deploy_timeout: 20
+
+# how long to wait for requests to complete before stopping old containers
+# Replaces stop_wait_time
+drain_timeout: 20
+
+# how long to wait for 'non proxy role' containers without healthchecks to stay in the running state
+readiness_delay: 10
+```
diff --git a/docs/upgrading/index.md b/docs/upgrading/index.md
new file mode 100644
index 0000000..4c9cfbd
--- /dev/null
+++ b/docs/upgrading/index.md
@@ -0,0 +1,5 @@
+---
+search: false
+redirect_to:
+ - /docs/upgrading/overview/
+---
diff --git a/docs/upgrading/network-changes.md b/docs/upgrading/network-changes.md
new file mode 100644
index 0000000..a8ef205
--- /dev/null
+++ b/docs/upgrading/network-changes.md
@@ -0,0 +1,15 @@
+---
+title: Network changes
+---
+
+# Network changes
+
+`kamal-proxy` needs a stable hostname for the container that it is routing to. This is so that it can identify and route traffic to the container across restarts.
+
+Using the default `bridge` network, application containers are assigned IP addresses, but they are not stable across restarts.
+
+So instead we will create and use a custom network called `kamal`.
+
+If you have custom requirements for your network, you can create the `kamal` network yourself before deploying with Kamal, or use a docker-setup hook to configure the network when running `kamal setup`.
+
+Accessories will also run from within the `kamal` network.
diff --git a/docs/upgrading/overview.md b/docs/upgrading/overview.md
new file mode 100644
index 0000000..70db71b
--- /dev/null
+++ b/docs/upgrading/overview.md
@@ -0,0 +1,106 @@
+---
+title: "Kamal 2: Upgrade Guide"
+---
+
+# Kamal 2: Upgrade Guide
+
+There are some significant differences between Kamal 1 and Kamal 2.
+
+- The Traefik proxy has been [replaced by kamal-proxy](../proxy-changes)
+- Kamal will run all containers in a [custom docker network](../network-changes)
+- There are some backward incompatible [configuration changes](../configuration-changes)
+- How we pass secrets to containers [has changed](../secrets-changes)
+
+## [Upgrade steps](#upgrade-steps)
+
+### Upgrade to Kamal 1.9.x
+
+If you are planning to do in-place upgrades of servers, you should first upgrade to Kamal 1.9, as it has support for downgrading.
+
+If using gem directly, you can run:
+
+```
+gem install kamal --version 1.9.0
+```
+
+Confirm you can deploy your application with Kamal 1.9.
+
+### Upgrade to Kamal 2
+
+If using the gem directly, run:
+
+```
+gem install kamal
+```
+
+### Make configuration changes
+
+You'll need to [convert your configuration](../configuration-changes) to work with Kamal 2.
+
+You can test whether the new configuration is valid by running:
+
+```bash
+$ kamal config
+```
+
+If you have multiple destinations, you should test each ones configuration:
+
+```bash
+$ kamal config -d staging
+$ kamal config -d beta
+```
+
+### Move from .env to .kamal/secrets
+
+Follow the steps [here](../secrets-changes).
+
+## [In-place upgrades](#in-place-upgrades)
+
+**Warning: Test this in a non-production environment first, if possible**
+
+### Upgrading
+
+You can then upgrade with:
+
+```
+$ kamal upgrade [-d ]
+```
+
+You'll need to do this separately for each destination.
+
+The `kamal upgrade` command will:
+
+1. Stop and remove the Traefik proxy
+2. Create a `kamal` docker network, if one doesn't exist
+3. Start a `kamal-proxy` container in the new network
+4. Reboot the current deployed version of the app container in the new network
+5. Tell `kamal-proxy` to send traffic to it
+6. Reboot all accessories in the new network
+
+### Avoiding downtime
+
+If you are running your application on multiple servers, and want to avoid downtime you can do a rolling upgrade:
+
+```
+$ kamal upgrade --rolling [-d ]
+```
+
+This will follow the same steps as above, but host by host.
+
+Alternatively you can run the command host by host:
+
+```
+$ kamal upgrade -h 127.0.0.1[,127.0.0.2]
+```
+
+You could additionally use the [pre-proxy-reboot](../hooks/pre-proxy-reboot.md) and [post-proxy-reboot](../hooks/post-proxy-reboot.md) hooks to manually remove your server from upstream load balancers, to ensure no requests are dropped during the upgrade process.
+
+### Downgrading
+
+If you want to reverse your changes and go back to Kamal 1.9.
+
+1. Uninstall Kamal 2.0.
+2. Confirm you are running Kamal 1.9, by running `kamal version`
+3. Run the `kamal downgrade` command. It has the same options as `kamal upgrade` and will reverse the process
+
+The upgrade and downgrade commands can be re-run against servers that have already been upgraded or downgraded.
diff --git a/docs/upgrading/proxy-changes.md b/docs/upgrading/proxy-changes.md
new file mode 100644
index 0000000..774afa4
--- /dev/null
+++ b/docs/upgrading/proxy-changes.md
@@ -0,0 +1,75 @@
+---
+title: Replacing Traefik with kamal-proxy
+---
+
+# Proxy changes
+
+In Kamal 1, we used [Traefik](https://traefik.io/traefik) to enable gapless deployments.
+
+For version 2, we are using [kamal-proxy](https://github.com/basecamp/kamal-proxy), a custom proxy called built specifically for Kamal.
+
+## [Why we are dropping Traefik](#dropping-traefik)
+
+### Imperative vs Declarative
+
+Traefik is not a great fit for Kamal. Kamal is an imperative tool, while Traefik is declarative.
+
+This means that we need to ask Traefik to do things, and then poll it to see when it's done.
+
+### Labels
+
+We used Traefik's Docker provider. It requires adding labels to containers, which Traefik uses to configure itself.
+
+It is flexible and there are a lot of options for things you can do with the labels. But it requires that you understand and use Traefik's [general purpose configuration](https://doc.traefik.io/traefik/providers/docker/) even to accomplish simple tasks.
+
+Container labels are immutable, so you can't tell Traefik to stop routing requests. To successfully drain containers, we had to resort to modifying healthchecks to force the container's into an unhealthy state.
+
+### Overly flexible
+
+Using Traefik labels, it is possible to get Kamal to do things it was not initially designed to do, like integrating Let's Encrypt, or running multiple application on one server.
+
+These use cases were unsupported and error prone though, and we wanted to provide simpler built solutions for those common requirements.
+
+### Hard to understand errors
+
+Traefik has its own domain language — Routers, Services, Endpoints. So if it failed the errors would be in that language and disconnected from what Kamal was doing. This made it tricky to diagnose failures.
+
+### Other options
+
+There are other proxies available, and Traefik has other configuration options, such as the file provider.
+
+However to evolve Kamal it became clear that building our own proxy would give us the control we needed to efficiently build and develop new features.
+
+We wanted:
+- An imperative proxy — i.e no polling
+- A 1-1 mapping between kamal commands and proxy commands
+- Clear error messages
+- Support for new commands
+- Deploy-time rather than boot-time config, so we can change it without restarting
+
+It was clear that we to get this we'd need to build the proxy ourselves.
+
+## [kamal-proxy](#kamal-proxy)
+
+[kamal-proxy](https://github.com/basecamp/kamal-proxy) is written in Go.
+
+It has minimal configuration so that we can run multiple applications against a single proxy without configuration clashes.
+
+Configuration (timeouts, logging, buffering etc) is supplied via commands at deploy time and only applies to the application being deployed.
+
+It uses blocking commands, so when you deploy the command will respond when the deployment is complete.
+
+It has support for:
+- Automatic TLS via Let's Encrypt
+- Host based routing
+- Request and response buffering
+- Maximum requests and response sizes
+
+And coming soon to Kamal:
+- Pausing requests
+- Maintenance mode
+- Gradual rollouts
+
+The proxy is distributed as a container via [Docker Hub](https://hub.docker.com/repository/docker/basecamp/kamal-proxy).
+
+Kamal will ensure that a compatible version is in place before deploying.
diff --git a/docs/upgrading/secrets-changes.md b/docs/upgrading/secrets-changes.md
new file mode 100644
index 0000000..de1e52b
--- /dev/null
+++ b/docs/upgrading/secrets-changes.md
@@ -0,0 +1,57 @@
+---
+title: Secrets changes
+---
+
+# Secrets changes
+
+Secrets have moved from `.env`/`.env.rb` to `.kamal/secrets.`
+
+If you are using destinations, secrets will be read from `.kamal/secrets-` first or `.kamal/secrets` if it is not found.
+
+## [Interpolating secrets](#interpolating-secrets)
+
+The `kamal envify` and `kamal env` commands have been removed and secrets no longer have a separate lifecycle.
+
+If you were generating secrets with `kamal envify` you can instead use dotenv's [command](https://github.com/bkeepers/dotenv?tab=readme-ov-file#command-substitution) and [variable](https://github.com/bkeepers/dotenv?tab=readme-ov-file#variable-substitution) substitution.
+
+The substitution will be performed on demand when running kamal commands that needs them.
+
+```
+# .kamal/secrets
+
+SECRET_FROM_ENV=$SECRET_FROM_ENV
+SECRET_FROM_COMMAND=$(op read ...)
+```
+
+See [here](../configuration/environment-variables#using-kamal-secrets) for more details
+
+## [Environment variables in deploy.yml](#environment-variables-in-deployyml)
+
+In Kamal 1, `.env` was loaded into the environment, so you could refer to values from it via ERB in `deploy.yml`. This is no longer the case in Kamal 2. Values from `.kamal/secrets` are not loaded either.
+
+Kamal 1:
+
+```
+# .env
+SERVER_IP=127.0.0.1
+
+# config/deploy.yml
+servers
+ - <%= ENV["SERVER_IP"] %>
+```
+
+To make this work in Kamal 2, you can manually load `.env`.
+
+Kamal 2:
+
+```
+# .env
+SERVER_IP=127.0.0.1
+
+# config/deploy.yml
+
+<% require "dotenv"; Dotenv.load(".env") %>
+
+servers
+ - <%= ENV["SERVER_IP"] %>
+```
diff --git a/v1/docs/commands/details.md b/v1/docs/commands/details.md
index e427b15..388f448 100644
--- a/v1/docs/commands/details.md
+++ b/v1/docs/commands/details.md
@@ -4,7 +4,7 @@ title: Details
# kamal details
-Shows details of all your containers
+Shows details of all your containers.
```bash
$ kamal details -q
diff --git a/v1/docs/commands/env.md b/v1/docs/commands/env.md
index 11f7201..58ada86 100644
--- a/v1/docs/commands/env.md
+++ b/v1/docs/commands/env.md
@@ -8,7 +8,7 @@ Manage your environment files.
`kamal env push` uses secrets configuration in `config/deploy.yml` and env variables from `.env` to create and push env files to your hosts. Those files are passed to containers when they are booted.
-See also [`kamal envify`](../envify)
+See also [`kamal envify`](../envify).
Example:
diff --git a/v1/docs/commands/lock.md b/v1/docs/commands/lock.md
index a94a8bf..81de1c4 100644
--- a/v1/docs/commands/lock.md
+++ b/v1/docs/commands/lock.md
@@ -8,7 +8,7 @@ Manage deployment locks.
Commands that are unsafe to run concurrently will take a deploy lock while they run. The lock is the `kamal_lock` directory on the primary server.
-You can manage them directly - for example clearing a leftover lock from a failed command or preventing deployments during a maintanence window.
+You can manage them directly — for example clearing a leftover lock from a failed command or preventing deployments during a maintanence window.
```
$ kamal lock
diff --git a/v1/docs/commands/rollback.md b/v1/docs/commands/rollback.md
index cf68cf0..d6b4edc 100644
--- a/v1/docs/commands/rollback.md
+++ b/v1/docs/commands/rollback.md
@@ -4,7 +4,7 @@ title: kamal rollback
# kamal rollback
-You can rollback a deployment with `kamal rollback`
+You can rollback a deployment with `kamal rollback`.
If you've discovered a bad deploy, you can quickly rollback to a previous image. You can see what old containers are available for rollback by running `kamal app containers -q`. It'll give you a presentation similar to `kamal app details`, but include all the old containers as well.
diff --git a/v1/docs/commands/server.md b/v1/docs/commands/server.md
index 72fa8f7..0e4b006 100644
--- a/v1/docs/commands/server.md
+++ b/v1/docs/commands/server.md
@@ -56,4 +56,4 @@ Run an interactive command on the server.
$ kamal server exec --interactive "/bin/bash"
Running '/bin/bash' on 867.53.0.9 interactively...
root@server:~#
-```
\ No newline at end of file
+```
diff --git a/v1/docs/configuration/accessories.md b/v1/docs/configuration/accessories.md
index c8c0923..58dff2e 100644
--- a/v1/docs/configuration/accessories.md
+++ b/v1/docs/configuration/accessories.md
@@ -4,39 +4,42 @@ 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 ` to boot an accessory.
See `kamal accessory --help` for more information.
## [Configuring accessories](#configuring-accessories)
-First define the accessory in the `accessories`
+First define the accessory in the `accessories`:
+
```yaml
accessories:
mysql:
```
+
## [Service name](#service-name)
-This is used in the service label and defaults to `-`
-where `` is the main service name from the root configuration
+This is used in the service label and defaults to `-` where `` is the main service name from the root configuration:
+
```yaml
service: mysql
```
+
## [Image](#image)
-The Docker image to use, prefix with a registry if not using Docker hub
+The Docker image to use, prefix with a registry if not using Docker hub:
+
```yaml
image: mysql:8.0
```
+
## [Accessory hosts](#accessory-hosts)
-Specify one of `host`, `hosts` or `roles`
+Specify one of `host`, `hosts` or `roles`:
+
```yaml
host: mysql-db1
hosts:
@@ -45,63 +48,76 @@ Specify one of `host`, `hosts` or `roles`
roles:
- mysql
```
+
## [Custom command](#custom-command)
-You can set a custom command to run in the container, if you do not want to use the default
+You can set a custom command to run in the container, if you do not want to use the default:
+
```yaml
cmd: "bin/mysqld"
```
+
## [Port mappings](#port-mappings)
-See https://docs.docker.com/network/, especially note the warning about the security
-implications of exposing ports publicly.
+See https://docs.docker.com/network/, especially note the warning about the security implications of exposing ports publicly.
+
```yaml
port: "127.0.0.1:3306:3306"
```
+
## [Labels](#labels)
+
```yaml
labels:
app: myapp
```
+
## [Options](#options)
-These are passed to the Docker run command in the form `--`
+
+These are passed to the Docker run command in the form `--`:
+
```yaml
options:
restart: always
cpus: 2
```
+
## [Environment variables](#environment-variables)
-See [Environment variables](../environment-variables) for more information
+
+See [Environment variables](../environment-variables) for more information:
+
```yaml
env:
...
```
+
## [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.
ERB files will be evaluated before being copied.
+
```yaml
files:
- config/my.cnf.erb:/etc/mysql/my.cnf
- config/myoptions.cnf:/etc/mysql/myoptions.cnf
```
+
## [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:
- mysql-logs:/var/log/mysql
```
+
## [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:
- /path/to/mysql-logs:/var/log/mysql
diff --git a/v1/docs/configuration/booting.md b/v1/docs/configuration/booting.md
index 8825641..2a48bcb 100644
--- a/v1/docs/configuration/booting.md
+++ b/v1/docs/configuration/booting.md
@@ -4,7 +4,6 @@ title: Booting
# Booting
-
When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
Kamal’s default is to boot new containers on all hosts in parallel. But you can control this with the boot configuration.
@@ -12,14 +11,17 @@ Kamal’s default is to boot new containers on all hosts in parallel. But you ca
## [Fixed group sizes](#fixed-group-sizes)
Here we boot 2 hosts at a time with a 10 second gap between each group.
+
```yaml
boot:
limit: 2
wait: 10
```
+
## [Percentage of hosts](#percentage-of-hosts)
Here we boot 25% of the hosts at a time with a 2 second gap between each group.
+
```yaml
boot:
limit: 25%
diff --git a/v1/docs/configuration/builders.md b/v1/docs/configuration/builders.md
index a9507a2..37a2fdb 100644
--- a/v1/docs/configuration/builders.md
+++ b/v1/docs/configuration/builders.md
@@ -86,7 +86,7 @@ If not set, then the default target is used:
target: production
```
-## [Build Arguments](#build-arguments)
+## [Build arguments](#build-arguments)
Any additional build arguments, passed to `docker build` with `--build-arg =`:
@@ -112,7 +112,7 @@ Values are read from the environment:
- SECRET2
```
-## [Referencing Build Secrets](#referencing-build-secrets)
+## [Referencing build secrets](#referencing-build-secrets)
```shell
# Copy Gemfiles
diff --git a/v1/docs/configuration/docker-registry.md b/v1/docs/configuration/docker-registry.md
index 5e5dcfe..f356693 100644
--- a/v1/docs/configuration/docker-registry.md
+++ b/v1/docs/configuration/docker-registry.md
@@ -4,11 +4,9 @@ title: Registry
# Registry
-
The default registry is Docker Hub, but you can change it using registry/server:
-A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret
-in the local environment.
+A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret in the local environment.
```yaml
registry:
@@ -18,9 +16,10 @@ registry:
password:
- DOCKER_REGISTRY_TOKEN
```
+
## [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 12hrs. In order to not have 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 12hrs. In order to not have 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:
@@ -28,19 +27,18 @@ registry:
username: AWS
password: <%= %x(aws ecr get-login-password) %>
```
+
## [Using GCP Artifact Registry as the container registry](#using-gcp-artifact-registry-as-the-container-registry)
-To sign into Artifact Registry, you would 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 a roles/artifactregistry.writer role should be sufficient.
+
+To sign into Artifact Registry, you would 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 a roles/artifactregistry.writer role should be sufficient.
Once the service account is ready, you need to generate and download a JSON key, base64 encode it and add to .env:
```shell
echo "KAMAL_REGISTRY_PASSWORD=$(base64 -i /path/to/key.json)" | tr -d "\\n" >> .env
```
-Use the env variable as password along with _json_key_base64 as username.
-Here’s the final configuration:
+
+Use the env variable as password along with _json_key_base64 as username. Here’s the final configuration:
```yaml
registry:
@@ -49,9 +47,11 @@ registry:
password:
- KAMAL_REGISTRY_PASSWORD
```
+
## [Validating the configuration](#validating-the-configuration)
You can validate the configuration by running:
+
```shell
kamal registry login
```
diff --git a/v1/docs/configuration/environment-variables.md b/v1/docs/configuration/environment-variables.md
index 04c17f8..8c1939f 100644
--- a/v1/docs/configuration/environment-variables.md
+++ b/v1/docs/configuration/environment-variables.md
@@ -4,40 +4,37 @@ title: Environment variables
# Environment variables
-
-Environment variables can be set directory in the Kamal configuration or
-for loaded from a .env file, for secrets that should not be checked into Git.
+Environment variables can be set directory in the Kamal configuration or for loaded from a .env file, for secrets that should not be checked into Git.
## [Reading environment variables from the configuration](#reading-environment-variables-from-the-configuration)
Environment variables can be set directly in the configuration file.
These are passed to the docker run command when deploying.
+
```yaml
env:
DATABASE_HOST: mysql-db1
DATABASE_PORT: 3306
```
+
## [Using .env file to load required environment variables](#using-.env-file-to-load-required-environment-variables)
-Kamal uses dotenv to automatically load environment variables set in the .env file present
-in the application root.
+Kamal uses dotenv to automatically load environment variables set in the .env file present in the application root.
+
+This file can be used to set variables like KAMAL_REGISTRY_PASSWORD or database passwords. But for this reason you must ensure that .env files are not checked into Git or included in your Dockerfile! The format is just key-value like:
-This file can be used to set variables like KAMAL_REGISTRY_PASSWORD or database passwords.
-But for this reason you must ensure that .env files are not checked into Git or included
-in your Dockerfile! The format is just key-value like:
```
KAMAL_REGISTRY_PASSWORD=pw
DB_PASSWORD=secret123
```
+
See [Envify](/docs/commands/envify/) for how to use generated .env files.
-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. The file is not updated when deploying, only when running `kamal envify` or `kamal env push`.
-Unlike clear valies, secrets are not passed directly to the container,
- but are stored in an env file on the host
-The file is not updated when deploying, only when running `kamal envify` or `kamal env push`.
```yaml
env:
clear:
@@ -45,14 +42,15 @@ env:
secret:
- DB_PASSWORD
```
+
## [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).
The env variables can be specified with secret and clear values as explained above.
+
```yaml
env:
tags:
@@ -64,7 +62,9 @@ env:
secret:
- MYSQL_PASSWORD
```
+
## [Example configuration](#example-configuration)
+
```yaml
env:
clear:
diff --git a/v1/docs/configuration/healthchecks.md b/v1/docs/configuration/healthchecks.md
index ff0aed8..7d3a9ef 100644
--- a/v1/docs/configuration/healthchecks.md
+++ b/v1/docs/configuration/healthchecks.md
@@ -4,70 +4,76 @@ title: Healthcheck configuration
# Healthcheck configuration
+On roles that are running Traefik, Kamal will supply a default healthcheck to `docker run`. For other roles, by default no healthcheck is supplied.
-On roles that are running Traefik, Kamal will supply a default healthcheck to `docker run`.
-For other roles, by default no healthcheck is supplied.
+If no healthcheck is supplied and the image does not define one, they we wait for the container to reach a running state and then pause for the readiness delay.
-If no healthcheck is supplied and the image does not define one, they we wait for the container
-to reach a running state and then pause for the readiness delay.
-
-The default healthcheck is `curl -f http://localhost:/`, so it assumes that `curl`
-is available within the container.
+The default healthcheck is `curl -f http://localhost:/`, so it assumes that `curl` is available within the container.
## [Healthcheck options](#healthcheck-options)
These go under the `healthcheck` key in the root or role configuration.
+
```yaml
healthcheck:
```
+
## [Command](#command)
-The command to run, defaults to `curl -f http://localhost:/` on roles running Traefik
+The command to run, defaults to `curl -f http://localhost:/` on roles running Traefik:
+
```yaml
cmd: "curl -f http://localhost"
```
+
## [Interval](#interval)
-The Docker healthcheck interval, defaults to `1s`
+The Docker healthcheck interval, defaults to `1s`:
+
```yaml
interval: 10s
```
+
## [Max attempts](#max-attempts)
-The maximum number of times we poll the container to see if it is healthy, defaults to `7`
-Each check is separated by an increasing interval starting with 1 second.
+The maximum number of times we poll the container to see if it is healthy, defaults to `7`. Each check is separated by an increasing interval starting with 1 second.
+
```yaml
max_attempts: 3
```
+
## [Port](#port)
-The port to use in the healthcheck, defaults to `3000`
+The port to use in the healthcheck, defaults to `3000`:
+
```yaml
port: "80"
```
+
## [Path](#path)
-The path to use in the healthcheck, defaults to `/up`
+The path to use in the healthcheck, defaults to `/up`:
+
```yaml
path: /health
```
+
## [Cords for zero-downtime deployments](#cords-for-zero-downtime-deployments)
-The cord file is used for zero-downtime deployments. The healthcheck is augmented with a check
-for the existance of the file. This allows us to delete the file and force the container to
-become unhealthy, causing Traefik to stop routing traffic to it.
+The cord file is used for zero-downtime deployments. The healthcheck is augmented with a check for the existence of the file. This allows us to delete the file and force the container to become unhealthy, causing Traefik to stop routing traffic to it.
+
+Kamal mounts a volume at this location and creates the file before starting the container. You can set the value to `false` to disable the cord file, but this loses the zero-downtime guarantee.
-Kamal mounts a volume at this location and creates the file before starting the container.
-You can set the value to `false` to disable the cord file, but this loses the zero-downtime
-guarantee.
+The default value is `/tmp/kamal-cord`:
-The default value is `/tmp/kamal-cord`
```yaml
cord: /cord
```
+
## [Log lines](#log-lines)
-Number of lines to log from the container when the healthcheck fails, defaults to `50`
+Number of lines to log from the container when the healthcheck fails, defaults to `50`:
+
```yaml
log_lines: 100
```
diff --git a/v1/docs/configuration/index.md b/v1/docs/configuration/index.md
index 338d246..eaaa1c5 100644
--- a/v1/docs/configuration/index.md
+++ b/v1/docs/configuration/index.md
@@ -1,5 +1,5 @@
---
search: false
redirect_to:
- - /v1/docs/configuration/configuration-overview/
+ - /v1/docs/configuration/overview/
---
diff --git a/v1/docs/configuration/logging.md b/v1/docs/configuration/logging.md
index 67d9bd9..4d36847 100644
--- a/v1/docs/configuration/logging.md
+++ b/v1/docs/configuration/logging.md
@@ -4,7 +4,6 @@ title: Custom logging configuration
# Custom logging configuration
-
Set these to control the Docker logging driver and options.
## [Logging settings](#logging-settings)
@@ -12,18 +11,23 @@ Set these to control the Docker logging driver and options.
These go under the logging key in the configuration file.
This can be specified in the root level or for a specific role.
+
```yaml
logging:
```
+
## [Driver](#driver)
-The logging driver to use, passed to Docker via `--log-driver`
+The logging driver to use, passed to Docker via `--log-driver`:
+
```yaml
driver: json-file
```
+
## [Options](#options)
-Any logging options to pass to the driver, passed to Docker via `--log-opt`
+Any logging options to pass to the driver, passed to Docker via `--log-opt`:
+
```yaml
options:
max-size: 100m
diff --git a/v1/docs/configuration/configuration-overview.md b/v1/docs/configuration/overview.md
similarity index 69%
rename from v1/docs/configuration/configuration-overview.md
rename to v1/docs/configuration/overview.md
index 3d3b4f0..0c35f73 100644
--- a/v1/docs/configuration/configuration-overview.md
+++ b/v1/docs/configuration/overview.md
@@ -4,195 +4,234 @@ title: Kamal Configuration
# Kamal Configuration
-
-Configuration is read from the `config/deploy.yml`
-
+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 use 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 use 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)
+
This is a required value. It is used as the container name prefix.
+
```yaml
service: myapp
```
+
## [The Docker image name](#the-docker-image-name)
The image will be pushed to the configured registry.
+
```yaml
image: my-image
```
+
## [Labels](#labels)
-Additional labels to add to the container
+Additional labels to add to the container:
+
```yaml
labels:
my-label: my-value
```
+
## [Additional volumes to mount into the container](#additional-volumes-to-mount-into-the-container)
+
```yaml
volumes:
- /path/on/host:/path/in/container:ro
```
+
## [Registry](#registry)
-The Docker registry configuration, see [Docker Registry](../docker-registry)
+The Docker registry configuration, see [Docker Registry](../docker-registry):
+
```yaml
registry:
...
```
+
## [Servers](#servers)
-The servers to deploy to, optionally with custom roles, see [Servers](../servers)
+The servers to deploy to, optionally with custom roles, see [Servers](../servers):
+
```yaml
servers:
...
```
+
## [Environment variables](#environment-variables)
-See [Environment variables](../environment-variables)
+See [Environment variables](../environment-variables):
+
```yaml
env:
...
```
+
## [Asset Bridging](#asset-bridging)
-Used for asset bridging across deployments, default to `nil`
+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:](#to-configure-this,-set-the-path-to-the-assets:)
+
```yaml
asset_path: /path/to/assets
```
+
## [Path to hooks, defaults to `.kamal/hooks`](#path-to-hooks,-defaults-to-`.kamal/hooks`)
-See [Hooks](/docs/hooks) for more information
+
+See [Hooks](/docs/hooks) for more information:
+
```yaml
hooks_path: /user_home/kamal/hooks
```
+
## [Require destinations](#require-destinations)
-Whether deployments require a destination to be specified, defaults to `false`
+Whether deployments require a destination to be specified, defaults to `false`:
+
```yaml
require_destination: true
```
+
## [The primary role](#the-primary-role)
-This defaults to `web`, but if you have no web role, you can change this
+This defaults to `web`, but if you have no web role, you can change this:
+
```yaml
primary_role: workers
```
+
## [Allowing empty roles](#allowing-empty-roles)
-Whether roles with no servers are allowed. Defaults to `false`.
+Whether roles with no servers are allowed. Defaults to `false`:
+
```yaml
allow_empty_roles: false
```
+
## [Stop wait time](#stop-wait-time)
-How long we wait for a container to stop before killing it, defaults to 30 seconds
+How long we wait for a container to stop before killing it, defaults to 30 seconds:
+
```yaml
stop_wait_time: 60
```
+
## [Retain containers](#retain-containers)
-How many old containers and images we retain, defaults to 5
+How many old containers and images we retain, defaults to 5:
+
```yaml
retain_containers: 3
```
+
## [Minimum version](#minimum-version)
-The minimum version of Kamal required to deploy this configuration, defaults to nil
+The minimum version of Kamal required to deploy this configuration, defaults to nil:
+
```yaml
minimum_version: 1.3.0
```
+
## [Readiness delay](#readiness-delay)
-Seconds to wait for a container to boot after is running, default 7
-This only applies to containers that do not specify a healthcheck
+Seconds to wait for a container to boot after is running, default 7. This only applies to containers that do not specify a healthcheck:
+
```yaml
readiness_delay: 4
```
+
## [Run directory](#run-directory)
-Directory to store kamal runtime files in on the host, default `.kamal`
+Directory to store kamal runtime files in on the host, default `.kamal`:
+
```yaml
run_directory: /etc/kamal
```
+
## [SSH options](#ssh-options)
-See [SSH](../ssh)
+See [SSH](../ssh):
+
```yaml
ssh:
...
```
+
## [Builder options](#builder-options)
-See [Builders](../builders)
+See [Builders](../builders):
+
```yaml
builder:
...
```
+
## [Accessories](#accessories)
-Additionals services to run in Docker, see [Accessories](../accessories)
+Additionals services to run in Docker, see [Accessories](../accessories):
+
```yaml
accessories:
...
```
+
## [Traefik](#traefik)
-The Traefik proxy is used for zero-downtime deployments, see [Traefik](../traefik)
+The Traefik proxy is used for zero-downtime deployments, see [Traefik](../traefik):
+
```yaml
traefik:
...
```
+
## [SSHKit](#sshkit)
-See [SSHKit](../sshkit)
+See [SSHKit](../sshkit):
+
```yaml
sshkit:
...
```
+
## [Boot options](#boot-options)
-See [Booting](../booting)
+See [Booting](../booting):
+
```yaml
boot:
...
```
+
## [Healthcheck](#healthcheck)
-Configuring healthcheck commands, intervals and timeouts, see [Healthchecks](../healthchecks)
+Configuring healthcheck commands, intervals and timeouts, see [Healthchecks](../healthchecks):
+
```yaml
healthcheck:
...
```
+
## [Logging](#logging)
-Docker logging configuration, see [Logging](../logging)
+Docker logging configuration, see [Logging](../logging):
+
```yaml
logging:
...
diff --git a/v1/docs/configuration/roles.md b/v1/docs/configuration/roles.md
index b97f6d2..e1812c6 100644
--- a/v1/docs/configuration/roles.md
+++ b/v1/docs/configuration/roles.md
@@ -4,40 +4,39 @@ title: Roles
# Roles
+Roles are used to configure different types of servers in the deployment. The most common use for this is to run a web servers and job servers.
-Roles are used to configure different types of servers in the deployment.
-The most common use for this is to run a web servers and job servers.
-
-Kamal expects there to be a `web` role, unless you set a different `primary_role`
-in the root configuration.
+Kamal expects there to be a `web` role, unless you set a different `primary_role` in the root configuration.
## [Role configuration](#role-configuration)
-Roles are specified under the servers key
+Roles are specified under the servers key:
+
```yaml
servers:
```
-## [Simple role configuration](#simple-role-configuration)
+## [Simple role configuration](#simple-role-configuration)
This can be a list of hosts, if you don't need custom configuration for the role.
-You can set tags on the hosts for custom env variables (see [Environment variables](../environment-variables))
+You can set tags on the hosts for custom env variables (see [Environment variables](../environment-variables)):
+
```yaml
web:
- 172.1.0.1
- 172.1.0.2: experiment1
- 172.1.0.2: [ experiment1, experiment2 ]
```
+
## [Custom role configuration](#custom-role-configuration)
-When there are other options to set, the list of hosts goes under the `hosts` key
+When there are other options to set, the list of hosts goes under the `hosts` key.
+
+By default only the primary role uses Traefik, but you can set `traefik` to change it.
-By default only the primary role uses Traefik, but you can set `traefik` to change
-it.
+You can also set a custom cmd to run in the container, and overwrite other settings from the root configuration.
-You can also set a custom cmd to run in the container, and overwrite other settings
-from the root configuration.
```yaml
workers:
hosts:
diff --git a/v1/docs/configuration/servers.md b/v1/docs/configuration/servers.md
index b2a0643..da220dd 100644
--- a/v1/docs/configuration/servers.md
+++ b/v1/docs/configuration/servers.md
@@ -4,29 +4,32 @@ title: Servers
# Servers
-
Servers are split into different roles, with each role having its own configuration.
-For simpler deployments though where all servers are identical, you can just specify a list of servers
-They will be implicitly assigned to the `web` role.
+For simpler deployments though where all servers are identical, you can just specify a list of servers. They will be implicitly assigned to the `web` role.
+
```yaml
servers:
- 172.0.0.1
- 172.0.0.2
- 172.0.0.3
```
+
## [Tagging servers](#tagging-servers)
Servers can be tagged, with the tags used to add custom env variables (see [Environment variables](../environment-variables)).
+
```yaml
servers:
- 172.0.0.1
- 172.0.0.2: experiments
- 172.0.0.3: [ experiments, three ]
```
+
## [Roles](#roles)
-For more complex deployments (e.g. if you are running job hosts), you can specify roles, and configure each separately (see [Roles](../roles))
+For more complex deployments (e.g. if you are running job hosts), you can specify roles, and configure each separately (see [Roles](../roles)):
+
```yaml
servers:
web:
diff --git a/v1/docs/configuration/ssh.md b/v1/docs/configuration/ssh.md
index 0faa7ed..0ecc009 100644
--- a/v1/docs/configuration/ssh.md
+++ b/v1/docs/configuration/ssh.md
@@ -4,9 +4,7 @@ title: SSH configuration
# SSH configuration
-
-Kamal uses SSH to connect run commands on your hosts.
-By default it will attempt to connect to the root user on port 22
+Kamal uses SSH to connect run commands on your hosts. By default it will attempt to connect to the root user on port 22.
If you are using non-root user, you may need to bootstrap your servers manually, before using them with Kamal. On Ubuntu, you’d do:
@@ -17,65 +15,73 @@ sudo apt install -y docker.io curl git
sudo usermod -a -G docker app
```
-
## [SSH options](#ssh-options)
The options are specified under the ssh key in the configuration file.
+
```yaml
ssh:
```
+
## [The SSH user](#the-ssh-user)
-Defaults to `root`
+Defaults to `root`:
```yaml
user: app
```
## [The SSH port](#the-ssh-port)
-Defaults to 22
+Defaults to 22:
+
```yaml
port: "2222"
```
+
## [Proxy host](#proxy-host)
-Specified in the form or @
+Specified in the form or @:
+
```yaml
proxy: root@proxy-host
```
+
## [Proxy command](#proxy-command)
-A custom proxy command, required for older versions of SSH
+A custom proxy command, required for older versions of SSH:
+
```yaml
proxy_command: "ssh -W %h:%p user@proxy"
```
+
## [Log level](#log-level)
-Defaults to `fatal`. Set this to debug if you are having
- SSH connection issues.
+Defaults to `fatal`. Set this to debug if you are having SSH connection issues.
+
```yaml
log_level: debug
```
-## [Keys Only](#keys-only)
-Set to true to use only private keys from keys and key_data parameters,
-even if ssh-agent offers more identities. This option is intended for
-situations where ssh-agent offers many different identites or you have
-a need to overwrite all identites and force a single one.
+## [Keys only](#keys-only)
+
+Set to true to use only private keys from keys and key_data parameters, even if ssh-agent offers more identities. This option is intended for situations where ssh-agent offers many different identities or you have a need to overwrite all identities and force a single one.
+
```yaml
keys_only: false
```
+
## [Keys](#keys)
-An array of file names of private keys to use for publickey
-and hostbased authentication
+An array of file names of private keys to use for publickey and hostbased authentication:
+
```yaml
keys: [ "~/.ssh/id.pem" ]
```
-## [Key Data](#key-data)
-An array of strings, with each element of the array being
-a raw private key in PEM format.
+## [Key data](#key-data)
+
+An array of strings, with each element of the array being a raw private key in PEM format.
+
```yaml
key_data: [ "-----BEGIN OPENSSH PRIVATE KEY-----" ]
```
diff --git a/v1/docs/configuration/sshkit.md b/v1/docs/configuration/sshkit.md
index f0b38a0..1bb70a3 100644
--- a/v1/docs/configuration/sshkit.md
+++ b/v1/docs/configuration/sshkit.md
@@ -4,29 +4,30 @@ title: SSHKit
# SSHKit
-
[SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal.
-The default settings should be sufficient for most use cases, but
-when connecting to a large number of hosts you may need to adjust
+The default settings should be sufficient for most use cases, but when connecting to a large number of hosts you may need to adjust
## [SSHKit options](#sshkit-options)
The options are specified under the sshkit key in the configuration file.
+
```yaml
sshkit:
```
+
## [Max concurrent starts](#max-concurrent-starts)
-Creating SSH connections concurrently can be an issue when deploying to many servers.
-By default Kamal will limit concurrent connection starts to 30 at a time.
+Creating SSH connections concurrently can be an issue when deploying to many servers. By default Kamal will limit concurrent connection starts to 30 at a time.
+
```yaml
max_concurrent_starts: 10
```
+
## [Pool idle timeout](#pool-idle-timeout)
-Kamal sets a long idle timeout of 900 seconds on connections to try to avoid
-re-connection storms after an idle period, like building an image or waiting for CI.
+Kamal sets a long idle timeout of 900 seconds on connections to try to avoid re-connection storms after an idle period, like building an image or waiting for CI.
+
```yaml
pool_idle_timeout: 300
```
diff --git a/v1/docs/configuration/traefik.md b/v1/docs/configuration/traefik.md
index 079727d..a9221eb 100644
--- a/v1/docs/configuration/traefik.md
+++ b/v1/docs/configuration/traefik.md
@@ -4,7 +4,6 @@ title: Traefik
# Traefik
-
Traefik is a reverse proxy, used by Kamal for zero-downtime deployments.
We start an instance on the hosts in it's own container.
@@ -18,30 +17,39 @@ During a deployment:
## [Traefik settings](#traefik-settings)
Traekik is configured in the root configuration under `traefik`.
+
```yaml
traefik:
```
+
## [Image](#image)
-The Traefik image to use, defaults to `traefik:v2.10`
+The Traefik image to use, defaults to `traefik:v2.10`:
+
```yaml
image: traefik:v2.9
```
+
## [Host port](#host-port)
-The host port to publish the Traefik container on, defaults to `80`
+The host port to publish the Traefik container on, defaults to `80`:
+
```yaml
host_port: "8080"
```
+
## [Disabling publishing](#disabling-publishing)
-To avoid publishing the Traefik container, set this to `false`
+To avoid publishing the Traefik container, set this to `false`:
+
```yaml
publish: false
```
+
## [Labels](#labels)
-Additional labels to apply to the Traefik container
+Additional labels to apply to the Traefik container:
+
```yaml
labels:
traefik.http.routers.catchall.entryPoints: http
@@ -50,9 +58,11 @@ Additional labels to apply to the Traefik container
traefik.http.routers.catchall.priority: "1"
traefik.http.services.unavailable.loadbalancer.server.port: "0"
```
+
## [Arguments](#arguments)
-Additional arguments to pass to the Traefik container
+Additional arguments to pass to the Traefik container:
+
```yaml
args:
entryPoints.http.address: ":80"
@@ -60,16 +70,20 @@ Additional arguments to pass to the Traefik container
accesslog: true
accesslog.format: json
```
+
## [Options](#options)
-Additional options to pass to `docker run`
+Additional options to pass to `docker run`:
+
```yaml
options:
cpus: 2
```
+
## [Environment variables](#environment-variables)
-See [Environment variables](../environment-variables)
+See [Environment variables](../environment-variables):
+
```yaml
env:
...
diff --git a/v1/docs/hooks/index.md b/v1/docs/hooks/index.md
index 005ee8f..f0bf80c 100644
--- a/v1/docs/hooks/index.md
+++ b/v1/docs/hooks/index.md
@@ -1,5 +1,5 @@
---
search: false
redirect_to:
- - /v1/docs/hooks/hooks-overview/
+ - /v1/docs/hooks/overview/
---
diff --git a/v1/docs/hooks/hooks-overview.md b/v1/docs/hooks/overview.md
similarity index 100%
rename from v1/docs/hooks/hooks-overview.md
rename to v1/docs/hooks/overview.md
diff --git a/v1/docs/index.md b/v1/docs/index.md
index 73c2744..e42e6e6 100644
--- a/v1/docs/index.md
+++ b/v1/docs/index.md
@@ -1,4 +1,5 @@
---
+search: false
redirect_to:
- /v1/docs/installation/
---
diff --git a/v1/index.md b/v1/index.md
index 97fa673..584cc97 100644
--- a/v1/index.md
+++ b/v1/index.md
@@ -1,4 +1,5 @@
---
+search: false
redirect_to:
- /v1/docs/
---
