From a53d0d25c3fbb3783fcd574c87d139610a36faa9 Mon Sep 17 00:00:00 2001 From: Dmytro Shteflyuk Date: Sat, 28 Sep 2024 22:45:20 -0400 Subject: [PATCH] Proofreading and minor corrections --- README.md | 2 +- docs/commands/accessory.md | 4 +- docs/commands/app.md | 2 +- docs/commands/audit.md | 2 +- docs/commands/build.md | 4 +- docs/commands/deploy.md | 13 +++--- docs/commands/details.md | 2 +- docs/commands/help.md | 2 +- docs/commands/init.md | 2 +- docs/commands/lock.md | 8 ++-- docs/commands/proxy.md | 12 +++--- docs/commands/prune.md | 2 +- docs/commands/registry.md | 2 +- docs/commands/remove.md | 2 +- docs/commands/rollback.md | 4 +- docs/commands/secrets.md | 20 +++++----- docs/commands/server.md | 4 +- docs/commands/setup.md | 7 ++-- docs/commands/view-all-commands.md | 2 +- docs/configuration/accessories.md | 16 ++++---- docs/configuration/aliases.md | 2 +- docs/configuration/booting.md | 6 +-- docs/configuration/builder-examples.md | 22 +++++------ docs/configuration/builders.md | 8 ++-- docs/configuration/cron.md | 2 +- docs/configuration/docker-registry.md | 14 +++---- docs/configuration/environment-variables.md | 16 ++++---- docs/configuration/logging.md | 2 +- docs/configuration/overview.md | 18 ++++----- docs/configuration/proxy.md | 29 +++++++------- docs/configuration/roles.md | 10 ++--- docs/configuration/servers.md | 4 +- docs/configuration/ssh.md | 12 +++--- docs/configuration/sshkit.md | 6 +-- docs/hooks/docker-setup.md | 2 +- docs/hooks/overview.md | 16 ++++---- docs/hooks/post-deploy.md | 4 +- docs/hooks/post-proxy-reboot.md | 2 +- docs/hooks/pre-build.md | 2 +- docs/hooks/pre-connect.md | 2 +- docs/hooks/pre-deploy.md | 2 +- docs/hooks/pre-proxy-reboot.md | 6 +-- docs/installation/index.md | 10 ++--- docs/upgrading/configuration-changes.md | 28 ++++++------- docs/upgrading/continuing-to-use-traefik.md | 12 +++--- docs/upgrading/network-changes.md | 4 +- docs/upgrading/overview.md | 44 ++++++++++----------- docs/upgrading/proxy-changes.md | 33 +++++++++------- docs/upgrading/secrets-changes.md | 8 ++-- v1/docs/installation/index.md | 8 ++-- 50 files changed, 226 insertions(+), 220 deletions(-) diff --git a/README.md b/README.md index e9430d7..8468c3d 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## Development -``` +```bash bundle install bundle exec jekyll serve --livereload ``` diff --git a/docs/commands/accessory.md b/docs/commands/accessory.md index 06c7d68..515ae52 100644 --- a/docs/commands/accessory.md +++ b/docs/commands/accessory.md @@ -10,7 +10,7 @@ They are not proxied, so rebooting will have a small period of downtime. You can Run `kamal accessory` to view and manage your accessories. -``` +```bash $ kamal accessory Commands: kamal accessory boot [NAME] # Boot new accessory service on host (use NAME=all to boot all accessories) @@ -29,7 +29,7 @@ To update an accessory, update the image in your config and run `kamal accessory Example: -``` +```bash $ kamal accessory boot all Running the pre-connect hook... INFO [bd04b11b] Running /usr/bin/env .kamal/hooks/pre-connect on localhost diff --git a/docs/commands/app.md b/docs/commands/app.md index 03b5522..1008121 100644 --- a/docs/commands/app.md +++ b/docs/commands/app.md @@ -10,7 +10,7 @@ To deploy new versions of the app, see `kamal deploy` and `kamal rollback`. You can use `kamal app exec` to [run commands on servers](../running-commands-on-servers). -``` +```bash $ kamal app Commands: kamal app boot # Boot app on servers (or reboot app if already running) diff --git a/docs/commands/audit.md b/docs/commands/audit.md index 4e73a22..1c473cd 100644 --- a/docs/commands/audit.md +++ b/docs/commands/audit.md @@ -4,7 +4,7 @@ title: Audit # kamal audit -Show the latest commands to have been run on each server. +Show the latest commands that have been run on each server. ```bash $ kamal audit diff --git a/docs/commands/build.md b/docs/commands/build.md index de0b230..cb0832f 100644 --- a/docs/commands/build.md +++ b/docs/commands/build.md @@ -6,7 +6,7 @@ title: Build Build your app images and push them to your servers. These commands are called indirectly by `kamal deploy` and `kamal redeploy`. -By default, Kamal will only build files you have committed to your git repository. However, you can configure Kamal to use the current context (instead of a git archive of HEAD) by setting the [build context](https://kamal-deploy.org/docs/configuration/builders/#build-context). +By default, Kamal will only build files you have committed to your Git repository. However, you can configure Kamal to use the current context (instead of a Git archive of HEAD) by setting the [build context](https://kamal-deploy.org/docs/configuration/builders/#build-context). ```bash $ kamal build @@ -22,7 +22,7 @@ Commands: Examples: -``` +```bash $ kamal build push Running the pre-connect hook... INFO [92ebc200] Running /usr/bin/env .kamal/hooks/pre-connect on localhost diff --git a/docs/commands/deploy.md b/docs/commands/deploy.md index b28c896..91576c7 100644 --- a/docs/commands/deploy.md +++ b/docs/commands/deploy.md @@ -4,16 +4,17 @@ title: Deploy # kamal deploy -Build and deploy your app to all servers. By default it will build the currently checked out version of the app. +Build and deploy your app to all servers. By default, it will build the currently checked out version of the app. -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. +Kamal will use [kamal-proxy](https://github.com/basecamp/kamal-proxy) to seamlessly move requests from the old version of the app to the new one without downtime. The deployment process is: -1. Login into the docker registry locally and on all servers -2. Build the app image, push it to the registry and pull it onto the servers + +1. Log in to the Docker registry locally and on all servers. +2. Build the app image, push it to the registry, and pull it onto the servers. 3. Ensure kamal-proxy is running and accepting traffic on ports 80 and 443. -4. Start a new container with the version of the app that matches the current git version hash. -5. Tell kamal-proxy to route traffic to the new container once it is responding with `200 OK` to `GET /up` +4. Start a new container with the version of the app that matches the current Git version hash. +5. Tell kamal-proxy to route traffic to the new container once it is responding with `200 OK` to `GET /up`. 6. Stop the old container running the previous version of the app. 7. Prune unused images and stopped containers to ensure servers don't fill up. diff --git a/docs/commands/details.md b/docs/commands/details.md index 388f448..fd11883 100644 --- a/docs/commands/details.md +++ b/docs/commands/details.md @@ -31,5 +31,5 @@ df8990876d14 registry:4443/app:75bf6fa40b975cbd8aec05abf7164e0982f185ac "/do CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 14857a6cb6b1 registry:4443/busybox:1.36.0 "sh -c 'echo \"Starti…" 42 minutes ago Up 42 minutes custom-busybox CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES -17f3ff88ff9f registry:4443/busybox:1.36.0 "sh -c 'echo \"Starti…" 42 minutes ago Up 42 minutes custom-busybox``` +17f3ff88ff9f registry:4443/busybox:1.36.0 "sh -c 'echo \"Starti…" 42 minutes ago Up 42 minutes custom-busybox ``` diff --git a/docs/commands/help.md b/docs/commands/help.md index 7ef4123..8c5c063 100644 --- a/docs/commands/help.md +++ b/docs/commands/help.md @@ -6,7 +6,7 @@ title: Help Displays help messages. Run `kamal help [command]` for details on a specific command. -``` +```bash $ kamal help kamal accessory # Manage accessories (db/redis/search) kamal app # Manage application diff --git a/docs/commands/init.md b/docs/commands/init.md index ef7cb36..601262b 100644 --- a/docs/commands/init.md +++ b/docs/commands/init.md @@ -6,7 +6,7 @@ title: Init Creates the files needed to deploy your application with `kamal`. -``` +```bash $ kamal init Created configuration file in config/deploy.yml Created .kamal/secrets file diff --git a/docs/commands/lock.md b/docs/commands/lock.md index 9cfefd6..1f47d02 100644 --- a/docs/commands/lock.md +++ b/docs/commands/lock.md @@ -8,9 +8,9 @@ Manage deployment locks. 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 maintenance window. +You can manage them directly — for example, clearing a leftover lock from a failed command or preventing deployments during a maintenance window. -``` +```bash $ kamal lock Commands: kamal lock acquire -m, --message=MESSAGE # Acquire the deploy lock @@ -26,7 +26,7 @@ $ kamal lock status INFO [f085f083] Running /usr/bin/env mkdir -p .kamal on server1 INFO [f085f083] Finished in 0.146 seconds with exit status 0 (successful). There is no deploy lock -$ kamal lock acquire -m "Maintanence in progress" +$ kamal lock acquire -m "Maintenance in progress" INFO [d9f63437] Running /usr/bin/env mkdir -p .kamal on server1 INFO [d9f63437] Finished in 0.138 seconds with exit status 0 (successful). Acquired the deploy lock @@ -35,7 +35,7 @@ $ kamal lock status INFO [9315755d] Finished in 0.130 seconds with exit status 0 (successful). Locked by: Deployer at 2024-04-05T08:32:46Z Version: 75bf6fa40b975cbd8aec05abf7164e0982f185ac -Message: Maintanence in progress +Message: Maintenance in progress $ kamal lock release INFO [7d5718a8] Running /usr/bin/env mkdir -p .kamal on server1 INFO [7d5718a8] Finished in 0.137 seconds with exit status 0 (successful). diff --git a/docs/commands/proxy.md b/docs/commands/proxy.md index 8c5f385..ee33281 100644 --- a/docs/commands/proxy.md +++ b/docs/commands/proxy.md @@ -10,7 +10,7 @@ Kamal uses [kamal-proxy](https://github.com/basecamp/kamal-proxy) to proxy reque $ kamal proxy Commands: kamal proxy boot # Boot proxy on servers - kamal proxy boot_config # Mange kamal-proxy boot configuration + kamal proxy boot_config # Manage kamal-proxy boot configuration kamal proxy details # Show details about proxy container from servers kamal proxy help [COMMAND] # Describe subcommands or one specific subcommand kamal proxy logs # Show log lines from proxy on servers @@ -29,9 +29,9 @@ You can also use [pre-proxy-reboot](../../hooks/pre-proxy-reboot) and [post-prox ## Boot configuration -You can manage boot configuration for kamal-proxy with `kamal proxy boot_config` +You can manage boot configuration for kamal-proxy with `kamal proxy boot_config`. -``` +```bash $ kamal proxy boot_config --help Usage: kamal proxy boot_config @@ -46,8 +46,8 @@ Options: [--docker-options=option=value option2=value2] # Docker options to pass to the proxy container ``` -When set the config will be stored on the server the proxy runs on. +When set, the config will be stored on the server the proxy runs on. -If you are running more than one application on a single server, there is only one proxy and the boot config is shared, so you'll need to manage the it centrally. +If you are running more than one application on a single server, there is only one proxy, and the boot config is shared, so you'll need to manage it centrally. -The configuration will be loaded at boot time, when calling `kamal proxy boot` or `kamal proxy reboot`. +The configuration will be loaded at boot time when calling `kamal proxy boot` or `kamal proxy reboot`. diff --git a/docs/commands/prune.md b/docs/commands/prune.md index 6529d79..10073a9 100644 --- a/docs/commands/prune.md +++ b/docs/commands/prune.md @@ -8,7 +8,7 @@ Prune old containers and images. Kamal keeps the last 5 deployed containers and the images they are using. Pruning deletes all older containers and images. -``` +```bash $ kamal help prune Commands: kamal prune all # Prune unused images and stopped containers diff --git a/docs/commands/registry.md b/docs/commands/registry.md index 2246083..dd8d56a 100644 --- a/docs/commands/registry.md +++ b/docs/commands/registry.md @@ -4,7 +4,7 @@ title: Registry # kamal registry -Log in and out of the docker registry on your servers. +Log in and out of the Docker registry on your servers. Examples: diff --git a/docs/commands/remove.md b/docs/commands/remove.md index a153458..878f082 100644 --- a/docs/commands/remove.md +++ b/docs/commands/remove.md @@ -4,6 +4,6 @@ title: Remove # kamal remove -This will remove app, kamal-proxy and accessory containers and log out of the docker registry. +This will remove the app, kamal-proxy, and accessory containers and log out of the Docker registry. It will prompt for confirmation unless you add the `-y` option. diff --git a/docs/commands/rollback.md b/docs/commands/rollback.md index d6b4edc..e3ddbc3 100644 --- a/docs/commands/rollback.md +++ b/docs/commands/rollback.md @@ -22,6 +22,6 @@ badb1aa51db4 registry.digitalocean.com/user/app:6ef8a6a84c525b123c5245345a8483 From the example above, we can see that `e5d9d7c2b898289dfbc5f7f1334140d984eedae4` was the last version, so it's available as a rollback target. We can perform this rollback by running `kamal rollback e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. -That'll stop `6ef8a6a84c525b123c5245345a8483f86d05a123` and then start a new container running the same image as `e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. Nothing to download from the registry. +That'll stop `6ef8a6a84c525b123c5245345a8483f86d05a123` and then start a new container running the same image as `e5d9d7c2b898289dfbc5f7f1334140d984eedae4`. Nothing needs to be downloaded from the registry. -**Note:** By default old containers are pruned after 3 days when you run `kamal deploy`. +**Note:** By default, old containers are pruned after 3 days when you run `kamal deploy`. diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md index 2bb6b7c..3f3f9d9 100644 --- a/docs/commands/secrets.md +++ b/docs/commands/secrets.md @@ -12,13 +12,13 @@ Commands: kamal secrets help [COMMAND] # Describe subcommands or one specific subcommand ``` -Use these to read secrets from common password managers (currently 1Password, LastPass and Bitwarden). +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: +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` -``` +```shell # .kamal/secrets SECRETS=$(kamal secrets fetch ...) @@ -29,9 +29,9 @@ DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS) ## 1Password -Use the adaptor `1password`: +Use the adapter `1password`: -``` +```bash # Fetch from item `MyItem` in the vault `MyVault` kamal secrets fetch --adapter 1password --account myaccount --from MyVault/MyItem REGISTRY_PASSWORD DB_PASSWORD @@ -42,7 +42,7 @@ kamal secrets fetch --adapter 1password --account myaccount --from MyVault/MyIte 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 +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 @@ -52,9 +52,9 @@ kamal secrets extract MyVault/MyItem/REGISTRY_PASSWORD ## LastPass -Use the adaptor `lastpass`: +Use the adapter `lastpass`: -``` +```bash # Fetch passwords kamal secrets fetch --adapter lastpass --account email@example.com REGISTRY_PASSWORD DB_PASSWORD @@ -71,9 +71,9 @@ kamal secrets extract MyFolder/REGISTRY_PASSWORD ## Bitwarden -Use the adaptor `bitwarden`: +Use the adapter `bitwarden`: -``` +```bash # Fetch passwords kamal secrets fetch --adapter bitwarden --account email@example.com REGISTRY_PASSWORD DB_PASSWORD diff --git a/docs/commands/server.md b/docs/commands/server.md index 0e4b006..9dcbada 100644 --- a/docs/commands/server.md +++ b/docs/commands/server.md @@ -14,9 +14,9 @@ Commands: ## [Bootstrap server](#bootstrap-server) -You can run `kamal server bootstrap` to setup docker on your hosts. +You can run `kamal server bootstrap` to set up Docker on your hosts. -It will check if docker is installed and if not it will attempt to install it via [get.docker.com](https://get.docker.com/). +It will check if Docker is installed and, if not, it will attempt to install it via [get.docker.com](https://get.docker.com/). ```bash $ kamal server bootstrap diff --git a/docs/commands/setup.md b/docs/commands/setup.md index 7bfee49..41ec81f 100644 --- a/docs/commands/setup.md +++ b/docs/commands/setup.md @@ -7,6 +7,7 @@ title: Setup Kamal setup will run everything required to deploy an application to a fresh host. It will: -1. Install docker on all servers, if it has permission and it is not already installed -2. Boot all accessories -3. Deploy the app (see [`kamal deploy`](../deploy)) + +1. Install Docker on all servers, if it has permission and it is not already installed. +2. Boot all accessories. +3. Deploy the app (see [`kamal deploy`](../deploy)). diff --git a/docs/commands/view-all-commands.md b/docs/commands/view-all-commands.md index 1acb015..6731ff4 100644 --- a/docs/commands/view-all-commands.md +++ b/docs/commands/view-all-commands.md @@ -6,7 +6,7 @@ title: View all commands You can view all of the commands by running `kamal --help`. -``` +```bash $ kamal --help Commands: kamal accessory # Manage accessories (db/redis/search) diff --git a/docs/configuration/accessories.md b/docs/configuration/accessories.md index 5fa78ad..aa00b4f 100644 --- a/docs/configuration/accessories.md +++ b/docs/configuration/accessories.md @@ -6,13 +6,13 @@ title: 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 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: @@ -21,7 +21,7 @@ accessories: ## [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 @@ -29,7 +29,7 @@ This is used in the service label and defaults to `-` where ## [Image](#image) -The Docker image to use, prefix with a registry if not using Docker hub: +The Docker image to use, prefix it with a registry if not using Docker Hub: ```yaml image: mysql:8.0 @@ -37,7 +37,7 @@ The Docker image to use, prefix with a registry if not using Docker hub: ## [Accessory hosts](#accessory-hosts) -Specify one of `host`, `hosts` or `roles`: +Specify one of `host`, `hosts`, or `roles`: ```yaml host: mysql-db1 @@ -50,7 +50,7 @@ Specify one of `host`, `hosts` or `roles`: ## [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" @@ -58,7 +58,7 @@ You can set a custom command to run in the container, if you do not want to use ## [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/, and especially note the warning about the security implications of exposing ports publicly. ```yaml port: "127.0.0.1:3306:3306" @@ -92,7 +92,7 @@ See [Environment variables](../environment-variables) for more information: ## [Copying files](#copying-files) -You can specify files to mount into the container. The format is `local:remote` where `local` is the path to the file on the local machine and `remote` is the path to the file in the container. +You can specify files to mount into the container. The format is `local:remote`, where `local` is the path to the file on the local machine and `remote` is the path to the file in the container. They will be uploaded from the local repo to the host and then mounted. diff --git a/docs/configuration/aliases.md b/docs/configuration/aliases.md index d95d763..83f0700 100644 --- a/docs/configuration/aliases.md +++ b/docs/configuration/aliases.md @@ -29,7 +29,7 @@ kamal console 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 fd916a7..6647861 100644 --- a/docs/configuration/booting.md +++ b/docs/configuration/booting.md @@ -6,11 +6,11 @@ title: 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. +Kamal’s default is to boot new containers on all hosts in parallel. However, 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: @@ -20,7 +20,7 @@ boot: ## [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: diff --git a/docs/configuration/builder-examples.md b/docs/configuration/builder-examples.md index fc2a63f..78a07d3 100644 --- a/docs/configuration/builder-examples.md +++ b/docs/configuration/builder-examples.md @@ -6,7 +6,7 @@ title: Builder examples ## [Using remote builder for single-arch](#using-remote-builder-for-single-arch) -If you're developing on ARM64 (like Apple Silicon), but you want to deploy on AMD64 (x86 64-bit), by default, Kamal will setup a local buildx configuration that does this through QEMU emulation. But this can be quite slow, especially on the first build. +If you're developing on ARM64 (like Apple Silicon), but you want to deploy on AMD64 (x86 64-bit), by default, Kamal will set up a local buildx configuration that does this through QEMU emulation. However, this can be quite slow, especially on the first build. If you want to speed up this process by using a remote AMD64 host to natively build the AMD64 part of the image, you can set a remote builder: @@ -20,11 +20,11 @@ Kamal will use the remote to build when deploying from an ARM64 machine, or buil **Note:** You must have Docker running on the remote host being used as a builder. This instance should only be shared for builds using the same registry and credentials. -## [Using remote builder for single-arch](#using-remote-builder-for-native-multi-arch) +## [Using remote builder for multi-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 arch matching your deployment server locally and the other arch remotely. +You can also build a multi-arch image. If a remote is set, Kamal will build the architecture matching your deployment server locally and the other architecture remotely. -So if you're developing on ARM64 (like Apple Silicon), it will build the ARM64 arch locally and the AMD64 arch remotely. +So if you're developing on ARM64 (like Apple Silicon), it will build the ARM64 architecture locally and the AMD64 architecture remotely. ```yaml builder: @@ -36,7 +36,7 @@ builder: ## [Using local builder for single-arch](#using-local-builder-for-single-arch) -If you always want to build locally for a single arch, Kamal will build the image using a local buildx instance. +If you always want to build locally for a single architecture, Kamal will build the image using a local buildx instance. ```yaml builder: @@ -45,7 +45,7 @@ builder: ## [Using a different Dockerfile or context when building](#using-a-different-dockerfile-or-context-when-building) -If you need to pass a different Dockerfile or context to the build command (e.g. if you're using a monorepo or you have different Dockerfiles), you can do so in the builder options: +If you need to pass a different Dockerfile or context to the build command (e.g., if you're using a monorepo or you have different Dockerfiles), you can do so in the builder options: ```yaml # Use a different Dockerfile @@ -64,7 +64,7 @@ builder: ## [Using multistage builder cache](#using-multistage-builder-cache) -Docker multistage build cache can speed up your builds. 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 @@ -93,7 +93,7 @@ builder: ### [GHA cache configuration](#gha-cache-configuration) -To make it work on the GitHub action workflow you need to setup the buildx and expose [authentication configuration for the cache](https://docs.docker.com/build/cache/backends/gha/#authentication). +To make it work on the GitHub action workflow, you need to set up the buildx and expose [authentication configuration for the cache](https://docs.docker.com/build/cache/backends/gha/#authentication). Example setup (in .github/workflows/sample-ci.yml): @@ -105,9 +105,9 @@ Example setup (in .github/workflows/sample-ci.yml): uses: crazy-max/ghaction-github-runtime@v3 ``` -When setup correctly you should see the cache entry/entries on the GHA workflow actions cache section. +When set up correctly, you should see the cache entry/entries on the GHA workflow actions cache section. -For further insights into build cache optimization, check out documentation on Docker's official website: https://docs.docker.com/build/cache/. +For further insights into build cache optimization, check out the documentation on Docker's official website: https://docs.docker.com/build/cache/. ## [Using build secrets for new images](#using-build-secrets-for-new-images) @@ -152,7 +152,7 @@ builder: This build argument can then be used in the Dockerfile: -``` +```dockerfile ARG RUBY_VERSION FROM ruby:$RUBY_VERSION-slim as base ``` diff --git a/docs/configuration/builders.md b/docs/configuration/builders.md index f81a04e..b0563a6 100644 --- a/docs/configuration/builders.md +++ b/docs/configuration/builders.md @@ -29,7 +29,7 @@ Allowed values are `amd64` and `arm64`: ## [Remote](#remote) -The connection string for a remote builder. If supplied Kamal will use this for builds that do not match the local architecture of the deployment host. +The connection string for a remote builder. If supplied, Kamal will use this for builds that do not match the local architecture of the deployment host. ```yaml remote: ssh://docker@docker-builder @@ -49,7 +49,7 @@ Defaults to true: 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 and is not compatible with the Docker driver: ```yaml cache: @@ -62,7 +62,7 @@ The image is only used for registry cache. Not compatible with the docker driver 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. +To use the local checkout instead, you can set the context to `.`, or a path to another directory. ```yaml context: . @@ -117,7 +117,7 @@ Values are read from .kamal/secrets. COPY Gemfile Gemfile.lock ./ # Install dependencies, including private repositories via access token -# Then remove bundle cache with exposed GITHUB_TOKEN) +# Then remove bundle cache with exposed GITHUB_TOKEN RUN --mount=type=secret,id=GITHUB_TOKEN \ BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \ bundle install && \ diff --git a/docs/configuration/cron.md b/docs/configuration/cron.md index 8aac582..d285312 100644 --- a/docs/configuration/cron.md +++ b/docs/configuration/cron.md @@ -15,4 +15,4 @@ servers: bash -c "cat config/crontab | crontab - && cron -f" ``` -This assumes the Cron settings are stored in `config/crontab`. +This assumes that the Cron settings are stored in `config/crontab`. diff --git a/docs/configuration/docker-registry.md b/docs/configuration/docker-registry.md index 2a8eef4..d42bca9 100644 --- a/docs/configuration/docker-registry.md +++ b/docs/configuration/docker-registry.md @@ -4,9 +4,9 @@ title: Registry # Registry -The default registry is Docker Hub, but you can change it using registry/server: +The default registry is Docker Hub, but you can change it using `registry/server`: -A reference to secret (in this case DOCKER_REGISTRY_TOKEN) will look up the secret in the local environment. +A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret in the local environment. ```yaml registry: @@ -19,7 +19,7 @@ registry: ## [Using AWS ECR as the container registry](#using-aws-ecr-as-the-container-registry) -You will need to have the aws CLI installed locally for this to work. AWS ECR’s access token is only valid for 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 12 hours. In order to avoid having to manually regenerate the token every time, you can use ERB in the `deploy.yml` file to shell out to the AWS CLI command and obtain the token: ```yaml registry: @@ -30,17 +30,17 @@ registry: ## [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 need to [create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating) and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions). Normally, assigning the `roles/artifactregistry.writer` role should be sufficient. Once the service account is ready, you need to generate and download a JSON key and base64 encode it: ```shell -base64 -i /path/to/key.json | tr -d "\\n") +base64 -i /path/to/key.json | tr -d "\\n" ``` -You'll then need to set the KAMAL_REGISTRY_PASSWORD secret to that value. +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 environment variable as the password along with `_json_key_base64` as the username. Here’s the final configuration: ```yaml registry: diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index 134f9bb..ec22630 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -4,13 +4,13 @@ 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. +These are passed to the `docker run` command when deploying. ```yaml env: @@ -28,25 +28,25 @@ 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. -``` +```shell 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. -``` +```shell 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. +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: @@ -60,7 +60,7 @@ env: 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). +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. diff --git a/docs/configuration/logging.md b/docs/configuration/logging.md index 4d36847..33422d5 100644 --- a/docs/configuration/logging.md +++ b/docs/configuration/logging.md @@ -10,7 +10,7 @@ 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. +This can be specified at the root level or for a specific role. ```yaml logging: diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md index b58ca45..9abce1d 100644 --- a/docs/configuration/overview.md +++ b/docs/configuration/overview.md @@ -8,9 +8,9 @@ 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) @@ -18,7 +18,7 @@ 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. -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 prefix a configuration section with `x-` to indicate that it is an extension. Kamal will ignore the extension and not raise an error. ## [The service name](#the-service-name) @@ -85,9 +85,9 @@ env: Used for asset bridging across deployments, default to `nil`. -If there are changes to CSS or JS files, we may get requests for the old versions on the new container and vice-versa. +If there are changes to CSS or JS files, we may get requests for the old versions on the new container, and vice versa. -To avoid 404s we can specify an asset path. Kamal will replace that path in the container with a mapped volume containing both sets of files. This requires that file names change when the contents change (e.g. by including a hash of the contents in the name). +To avoid 404s, we can specify an asset path. Kamal will replace that path in the container with a mapped volume containing both sets of files. This requires that file names change when the contents change (e.g., by including a hash of the contents in the name). To configure this, set the path to the assets: @@ -137,7 +137,7 @@ 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 @@ -145,7 +145,7 @@ 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 it is running, default 7. This only applies to containers that do not run a proxy or specify a healthcheck: @@ -163,7 +163,7 @@ deploy_timeout: 10 ## [Drain timeout](#drain-timeout) -How long to wait for a containers to drain, default 30: +How long to wait for a container to drain, default 30: ```yaml drain_timeout: 10 @@ -189,7 +189,7 @@ builder: ## [Accessories](#accessories) -Additionals services to run in Docker, see [Accessories](../accessories): +Additional services to run in Docker, see [Accessories](../accessories): ```yaml accessories: diff --git a/docs/configuration/proxy.md b/docs/configuration/proxy.md index 92ea5a8..ad05761 100644 --- a/docs/configuration/proxy.md +++ b/docs/configuration/proxy.md @@ -6,13 +6,13 @@ title: 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. -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. +They are application-specific, so they 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`. +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. +It is disabled by default on all other roles but can be enabled by setting `proxy: true` or providing a proxy configuration. ```yaml proxy: @@ -27,7 +27,8 @@ If no hosts are set, then all requests will be forwarded, except for matching re ```yaml host: foo.example.com ``` -If multiple hosts are needed, these can be specified by comma separating the hosts. + +If multiple hosts are needed, these can be specified by comma-separating the hosts. ```yaml host: foo.example.com,bar.example.com @@ -47,7 +48,7 @@ Defaults to 80: 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 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: @@ -55,7 +56,7 @@ Defaults to false: ssl: true ``` -In the scenario where Let's Encrypt is not an option, or you already have your own certificates from a different Certificate Authority, you can configure kamal-proxy to load the certificate and the corresponding private key from disk: +In scenarios where Let's Encrypt is not an option, or you already have your own certificates from a different Certificate Authority, you can configure kamal-proxy to load the certificate and the corresponding private key from disk: ```yaml ssl_certificate_path: /data/cert/foo.example.com/fullchain.pem @@ -72,7 +73,7 @@ How long to wait for requests to complete before timing out, defaults to 30 seco ## [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. @@ -87,9 +88,9 @@ Once the app is up, the proxy will stop hitting the healthcheck endpoint. 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: @@ -102,7 +103,7 @@ You can also set the memory limit for buffering, which defaults to 1MB, anything ## [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: @@ -116,11 +117,11 @@ Configure request logging for the proxy. You can specify request and response he ## [Forward headers](#forward-headers) -Whether to forward the X-Forwarded-For and X-Forwarded-Proto headers. +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. +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 if 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 1aca44f..ddea9a3 100644 --- a/docs/configuration/roles.md +++ b/docs/configuration/roles.md @@ -4,7 +4,7 @@ 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 web servers and job servers. Kamal expects there to be a `web` role, unless you set a different `primary_role` in the root configuration. @@ -18,7 +18,7 @@ servers: ## [Simple role configuration](#simple-role-configuration) -This can be a list of hosts, if you don't need custom configuration for the role. +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)): @@ -33,13 +33,13 @@ You can set tags on the hosts for custom env variables (see [Environment variabl 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. +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. +For other roles, you can set it to `proxy: true` to enable it and inherit the root proxy configuration or provide a map of options to override the root configuration. 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: diff --git a/docs/configuration/servers.md b/docs/configuration/servers.md index da220dd..816710c 100644 --- a/docs/configuration/servers.md +++ b/docs/configuration/servers.md @@ -6,7 +6,7 @@ title: 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: @@ -28,7 +28,7 @@ servers: ## [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: diff --git a/docs/configuration/ssh.md b/docs/configuration/ssh.md index 8082565..2013444 100644 --- a/docs/configuration/ssh.md +++ b/docs/configuration/ssh.md @@ -4,9 +4,9 @@ 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 and 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: +If you are using a non-root user, you may need to bootstrap your servers manually before using them with Kamal. On Ubuntu, you’d do: ```shell sudo apt update @@ -49,7 +49,7 @@ Specified in the form or @: ## [Proxy command](#proxy-command) -A custom proxy command, required for older versions of SSH: +A custom proxy command is required for older versions of SSH: ```yaml proxy_command: "ssh -W %h:%p user@proxy" @@ -57,7 +57,7 @@ A custom proxy command, required for older versions of SSH: ## [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 @@ -65,7 +65,7 @@ Defaults to `fatal`. Set this to debug if you are having SSH connection issues. ## [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. +Set to `true` to use only private keys from the `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 need to overwrite all identities and force a single one. ```yaml keys_only: false @@ -73,7 +73,7 @@ Set to true to use only private keys from keys and key_data parameters, even if ## [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 public key and host-based authentication: ```yaml keys: [ "~/.ssh/id.pem" ] diff --git a/docs/configuration/sshkit.md b/docs/configuration/sshkit.md index f006de7..2033119 100644 --- a/docs/configuration/sshkit.md +++ b/docs/configuration/sshkit.md @@ -6,7 +6,7 @@ title: 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) @@ -18,7 +18,7 @@ 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 @@ -26,7 +26,7 @@ Creating SSH connections concurrently can be an issue when deploying to many ser ## [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, such as 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 5b953d4..ee3bec8 100644 --- a/docs/hooks/docker-setup.md +++ b/docs/hooks/docker-setup.md @@ -4,4 +4,4 @@ title: docker-setup # 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. +Run once Docker is installed on a server but before taking any application-specific actions. This is designed for performing any necessary configuration of Docker itself. diff --git a/docs/hooks/overview.md b/docs/hooks/overview.md index 3ba43c0..24f9182 100644 --- a/docs/hooks/overview.md +++ b/docs/hooks/overview.md @@ -10,20 +10,20 @@ Hooks should be stored in the **.kamal/hooks** folder. Running `kamal init` will You can change their location by setting `hooks_path` in the configuration file. -If the script returns a non-zero exit code the command will be aborted. +If the script returns a non-zero exit code, the command will be aborted. -`KAMAL_*` environment variables are available to the hooks command for fine-grained audit reporting, e.g. for triggering deployment reports or firing a JSON webhook. These variables include: +`KAMAL_*` environment variables are available to the hooks command for fine-grained audit reporting, e.g., for triggering deployment reports or firing a JSON webhook. These variables include: -- `KAMAL_RECORDED_AT` — UTC timestamp in ISO 8601 format, e.g. `2023-04-14T17:07:31Z` +- `KAMAL_RECORDED_AT` — UTC timestamp in ISO 8601 format, e.g., `2023-04-14T17:07:31Z` - `KAMAL_PERFORMER` — The local user performing the command (from `whoami`) -- `KAMAL_SERVICE` — The service name, e.g. app -- `KAMAL_SERVICE_VERSION` — An abbreviated service and version for use in messages, e.g. app@150b24f +- `KAMAL_SERVICE` — The service name, e.g., app +- `KAMAL_SERVICE_VERSION` — An abbreviated service and version for use in messages, e.g., app@150b24f - `KAMAL_VERSION` — The full version being deployed - `KAMAL_HOSTS` — A comma-separated list of the hosts targeted by the command - `KAMAL_COMMAND` — The command we are running -- `KAMAL_SUBCOMMAND` — *Optional:* The subcommand we are running -- `KAMAL_DESTINATION` — *Optional:* Destination, e.g. "staging" -- `KAMAL_ROLE` — *Optional:* Role targeted, e.g. "web" +- `KAMAL_SUBCOMMAND` — _Optional:_ The subcommand we are running +- `KAMAL_DESTINATION` — _Optional:_ Destination, e.g., "staging" +- `KAMAL_ROLE` — _Optional:_ Role targeted, e.g., "web" The available hooks are: diff --git a/docs/hooks/post-deploy.md b/docs/hooks/post-deploy.md index b18649e..b355116 100644 --- a/docs/hooks/post-deploy.md +++ b/docs/hooks/post-deploy.md @@ -4,9 +4,9 @@ title: post-deploy # 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. +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. -This could be used to broadcast a deployment message, or register the new version with an APM. +This could be used to broadcast a deployment message or register the new version with an APM. The command could look something like: diff --git a/docs/hooks/post-proxy-reboot.md b/docs/hooks/post-proxy-reboot.md index 5e8dd82..e79f93f 100644 --- a/docs/hooks/post-proxy-reboot.md +++ b/docs/hooks/post-proxy-reboot.md @@ -4,4 +4,4 @@ title: post-proxy-reboot # Hooks: post-proxy-reboot -Runs after rebooting the kamal-proxy container, see [pre-proxy-reboot](../pre-proxy-reboot) for details. +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 bfcf8cc..1e76018 100644 --- a/docs/hooks/pre-build.md +++ b/docs/hooks/pre-build.md @@ -4,4 +4,4 @@ title: pre-build # Hooks: pre-build -Used for pre-build checks, e.g. there are no uncommitted changes or that CI has passed. +Used for pre-build checks, e.g., ensuring 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 71ae464..b1a2a10 100644 --- a/docs/hooks/pre-connect.md +++ b/docs/hooks/pre-connect.md @@ -4,4 +4,4 @@ title: pre-connect # 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. +Runs before taking the deploy lock. For anything that needs 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 86b810c..3a7e356 100644 --- a/docs/hooks/pre-deploy.md +++ b/docs/hooks/pre-deploy.md @@ -4,4 +4,4 @@ title: pre-deploy # Hooks: pre-deploy -For final checks before deploying, e.g. checking CI completed. +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 7ea378b..5a9ef60 100644 --- a/docs/hooks/pre-proxy-reboot.md +++ b/docs/hooks/pre-proxy-reboot.md @@ -4,10 +4,10 @@ title: pre-proxy-reboot # Hooks: pre-proxy-reboot -Run before rebooting the kamal-proxy container, when you call `kamal proxy reboot`. +Run before rebooting the kamal-proxy container when you call `kamal proxy reboot`. -If you have the hook disable the current server in an external load balancer and use the --rolling flag, you can use this for a zero-downtime proxy reboot. +If you have the hook disabling the current server in an external load balancer and use the `--rolling` flag, you can use this for a zero-downtime proxy reboot. -With a rolling reboot hook will be called once for each server, with `KAMAL_HOSTS` containing the current server. With a non-rolling reboot it will be called just once. +With a rolling reboot, the hook will be called once for each server, with `KAMAL_HOSTS` containing the current server. With a non-rolling reboot, it will be called just once. Use the [post-proxy-reboot](../post-proxy-reboot) hook to re-enable the server. diff --git a/docs/installation/index.md b/docs/installation/index.md index c536ddd..d990974 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -10,7 +10,7 @@ If you have a Ruby environment available, you can install Kamal globally with: gem install kamal ``` -Otherwise, you can run a dockerized version via an alias (add this to your `~/.bashrc` or similar to simplify re-use). +Otherwise, you can run a dockerized version via an alias (add this to your `~/.bashrc` or similar to simplify reuse). On macOS, use: @@ -43,7 +43,7 @@ env: - RAILS_MASTER_KEY ``` -Set your `KAMAL_REGISTRY_PASSWORD` in your environment and edit your `.kamal/secrets` file to read it it (and your `RAILS_MASTER_KEY` for production with a Rails app). +Set your `KAMAL_REGISTRY_PASSWORD` in your environment and edit your `.kamal/secrets` file to read it (and your `RAILS_MASTER_KEY` for production with a Rails app). ```yaml KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD @@ -58,15 +58,15 @@ kamal setup This will: -1. Connect to the servers over SSH (using root by default, authenticated by your ssh key). -2. Install Docker on any server that might be missing it (using get.docker.com): root access is needed via ssh for this. +1. Connect to the servers over SSH (using root by default, authenticated by your SSH key). +2. Install Docker on any server that might be missing it (using get.docker.com): root access is needed via SSH for this. 3. Log into the registry both locally and remotely. 4. Build the image using the standard Dockerfile in the root of the application. 5. Push the image to the registry. 6. Pull the image from the registry onto the servers. 7. Ensure kamal-proxy is running and accepting traffic on ports 80 and 443. 8. Start a new container with the version of the app that matches the current git version hash. -9. Tell kamal-proxy to route traffic to the new container once it is responding with `200 OK` to `GET /up` +9. Tell kamal-proxy to route traffic to the new container once it is responding with `200 OK` to `GET /up`. 10. Stop the old container running the previous version of the app. 11. Prune unused images and stopped containers to ensure servers don't fill up. diff --git a/docs/upgrading/configuration-changes.md b/docs/upgrading/configuration-changes.md index 2f82dae..9f605ba 100644 --- a/docs/upgrading/configuration-changes.md +++ b/docs/upgrading/configuration-changes.md @@ -26,7 +26,7 @@ builder: ### 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: +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: @@ -45,22 +45,22 @@ builder: ### Driver -Kamal will now always use the docker container (link) driver by default. You can set the driver yourself to change this: +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. +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). +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. +If you were using custom Traefik labels or args, see the proxy configuration to determine 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. +kamal-proxy supports common requirements such as buffering, max request/response sizes, and forwarding headers, but it does not encompass 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. @@ -70,7 +70,7 @@ 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). +For roles running with a proxy, the healthchecks are performed externally by kamal-proxy, not via internal Docker healthchecks. You can configure them under [proxy/healthcheck](../../configuration/proxy#healthcheck). ```yaml proxy: @@ -80,7 +80,7 @@ proxy: timeout: 2 ``` -Please note that the healthchecks will use the `app_port` setting which defaults to port 80. Previously healthchecks defaulted to port 3000. You can change this back with: +Please note that the healthchecks will use the `app_port` setting, which defaults to port 80. Previously, healthchecks defaulted to port 3000. You can change this back with: ```yaml proxy: @@ -89,7 +89,7 @@ proxy: ### 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). +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: @@ -102,20 +102,20 @@ servers: 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. +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. +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 +# how long to wait for new containers to boot deploy_timeout: 20 -# how long to wait for requests to complete before stopping old containers +# 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 +# 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/continuing-to-use-traefik.md b/docs/upgrading/continuing-to-use-traefik.md index 563692b..b1de5c7 100644 --- a/docs/upgrading/continuing-to-use-traefik.md +++ b/docs/upgrading/continuing-to-use-traefik.md @@ -12,8 +12,8 @@ You can run it as a Kamal accessory, and route requests through it and then on t We'll need to change kamal-proxy's default boot config so that: -1. It doesn't publish ports on the host -1. It adds the labels Traefik needs to route requests to it +1. It doesn't publish ports on the host. +2. It adds the labels Traefik needs to route requests to it. Add a [pre-deploy hook](../../hooks/pre-deploy) for Traefik to pick up: @@ -47,7 +47,7 @@ accessories: ## Running with Traefik -When you call `kamal setup`, it will boot the Traefik accessory, call the pre-deploy hook to update kamal-proxy's boot config and then boot kamal-proxy and the app. +When you call `kamal setup`, it will boot the Traefik accessory, call the pre-deploy hook to update kamal-proxy's boot config, and then boot kamal-proxy and the app. Requests will flow from Traefik to kamal-proxy to your app. @@ -63,6 +63,6 @@ CONTAINER ID IMAGE If you are already running kamal-proxy, you'll need to: -1. Manually run the `kamal proxy boot_config set` command from the deploy hook -2. Run `kamal proxy reboot` to pick up those boot config changes -3. Run `kamal accessory boot traefik` to start Traefik +1. Manually run the `kamal proxy boot_config set` command from the deploy hook. +2. Run `kamal proxy reboot` to pick up those boot config changes. +3. Run `kamal accessory boot traefik` to start Traefik. diff --git a/docs/upgrading/network-changes.md b/docs/upgrading/network-changes.md index c843264..9ba97ff 100644 --- a/docs/upgrading/network-changes.md +++ b/docs/upgrading/network-changes.md @@ -8,8 +8,8 @@ title: Network changes 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`. +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`. +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 index e693f20..414039d 100644 --- a/docs/upgrading/overview.md +++ b/docs/upgrading/overview.md @@ -6,12 +6,12 @@ title: "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) +- 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). -If you want to continue using Traefik you can run it as an accessory, see [here](../continuing-to-use-traefik) for more details. +If you want to continue using Traefik, you can run it as an accessory; see [here](../continuing-to-use-traefik) for more details. ## [Upgrade steps](#upgrade-steps) @@ -19,9 +19,9 @@ If you want to continue using Traefik you can run it as an accessory, see [here] 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: +If using the gem directly, you can run: -``` +```bash gem install kamal --version 1.9.0 ``` @@ -31,7 +31,7 @@ Confirm you can deploy your application with Kamal 1.9. If using the gem directly, run: -``` +```bash gem install kamal ``` @@ -58,7 +58,7 @@ Follow the steps [here](../secrets-changes). ## [In-place upgrades](#in-place-upgrades) -**Warning: Test this in a non-production environment first, if possible** +**Warning: Test this in a non-production environment first, if possible.** ### Upgrading @@ -72,26 +72,26 @@ 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 +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 currently 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: +If you are running your application on multiple servers and want to avoid downtime, you can do a rolling upgrade: -``` +```bash $ 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: +Alternatively, you can run the command host by host: -``` +```bash $ kamal upgrade -h 127.0.0.1[,127.0.0.2] ``` @@ -99,10 +99,10 @@ You could additionally use the [pre-proxy-reboot](../hooks/pre-proxy-reboot.md) ### Downgrading -If you want to reverse your changes and go back to Kamal 1.9. +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 +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 index af20ed9..c7f69e2 100644 --- a/docs/upgrading/proxy-changes.md +++ b/docs/upgrading/proxy-changes.md @@ -6,11 +6,11 @@ title: 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. +For version 2, we are using [kamal-proxy](https://github.com/basecamp/kamal-proxy), a custom proxy built specifically for Kamal. ## [Why we are dropping Traefik](#dropping-traefik) -### Imperative vs Declarative +### Imperative vs. Declarative Traefik is not a great fit for Kamal. Kamal is an imperative tool, while Traefik is declarative. @@ -20,34 +20,35 @@ This means that we need to ask Traefik to do things, and then poll it to see whe 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. +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. +Container labels are immutable, so you can't tell Traefik to stop routing requests. To successfully drain containers, we had to resort to modifying health checks to force the containers 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. +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 applications on one server. -These use cases were unsupported and error prone though, and we wanted to provide simpler built solutions for those common requirements. +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. +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. +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 + +- An imperative proxy — i.e., no polling +- A 1-to-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. +It was clear that to achieve this, we'd need to build the proxy ourselves. ## [kamal-proxy](#kamal-proxy) @@ -55,17 +56,19 @@ It was clear that we to get this we'd need to build the proxy ourselves. 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. +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 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 +- Host-based routing - Request and response buffering -- Maximum requests and response sizes +- Maximum request and response sizes And coming soon to Kamal: + - Pausing requests - Maintenance mode - Gradual rollouts diff --git a/docs/upgrading/secrets-changes.md b/docs/upgrading/secrets-changes.md index 319f528..4880267 100644 --- a/docs/upgrading/secrets-changes.md +++ b/docs/upgrading/secrets-changes.md @@ -10,11 +10,11 @@ If you are using destinations, secrets will be read from `.kamal/secrets.