Skip to content

Commit f04bf3f

Browse files
djmbdjmb
authored
Merge pull request #119 from basecamp/kamal-2.1.0
Doc updates for Kamal 2.1
2 parents 9facf89 + d1b4ad2 commit f04bf3f

16 files changed

+176
-76
lines changed

‎_data/github.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
tag_name: 2.0.0
1+
tag_name: 2.1.0
22
v1:
3-
tag_name: 1.9.0
3+
tag_name: 1.9.1

‎_data/nav.yml

+2-2
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
- title: "Documentation"
22
url: /docs/
33
options:
4-
- title: "Version 2.0.0"
4+
- title: "Version 2.1.0"
55
url: /docs/
6-
- title: "Version 1.9.0"
6+
- title: "Version 1.9.1"
77
url: /v1/docs/
88

99
- title: "Source code"

‎docs/commands/version.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -8,5 +8,5 @@ Returns the version of Kamal you have installed.
88

99
```bash
1010
$ kamal version
11-
2.0.0
11+
2.1.0
1212
```

‎docs/configuration/accessories.md

+19-8
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,19 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/accessory.yml in the Kamal repository.
24
title: Accessories
35
---
46

57
# Accessories
68

7-
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.
9+
Accessories can be booted on a single host, a list of hosts, or on specific roles.
10+
The hosts do not need to be defined in the Kamal servers configuration.
811

9-
Accessories are managed separately from the main service — they are not updated when you deploy, and they do not have zero-downtime deployments.
12+
Accessories are managed separately from the main service — they are not updated
13+
when you deploy, and they do not have zero-downtime deployments.
1014

11-
Run `kamal accessory boot <accessory>` to boot an accessory. See `kamal accessory --help` for more information.
15+
Run `kamal accessory boot <accessory>` to boot an accessory.
16+
See `kamal accessory --help` for more information.
1217

1318
## [Configuring accessories](#configuring-accessories)
1419

@@ -21,7 +26,8 @@ accessories:
2126
2227
## [Service name](#service-name)
2328
24-
This is used in the service label and defaults to `<service>-<accessory>`, where `<service>` is the main service name from the root configuration:
29+
This is used in the service label and defaults to `<service>-<accessory>`,
30+
where `<service>` is the main service name from the root configuration:
2531

2632
```yaml
2733
service: mysql
@@ -58,7 +64,8 @@ You can set a custom command to run in the container if you do not want to use t
5864

5965
## [Port mappings](#port-mappings)
6066

61-
See https://docs.docker.com/network/, and especially note the warning about the security implications of exposing ports publicly.
67+
See https://docs.docker.com/network/, and especially note the warning about the security
68+
implications of exposing ports publicly.
6269

6370
```yaml
6471
port: "127.0.0.1:3306:3306"
@@ -92,7 +99,9 @@ See [Environment variables](../environment-variables) for more information:
9299

93100
## [Copying files](#copying-files)
94101

95-
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.
102+
You can specify files to mount into the container.
103+
The format is `local:remote`, where `local` is the path to the file on the local machine
104+
and `remote` is the path to the file in the container.
96105

97106
They will be uploaded from the local repo to the host and then mounted.
98107

@@ -106,7 +115,8 @@ ERB files will be evaluated before being copied.
106115

107116
## [Directories](#directories)
108117

109-
You can specify directories to mount into the container. They will be created on the host before being mounted:
118+
You can specify directories to mount into the container. They will be created on the host
119+
before being mounted:
110120

111121
```yaml
112122
directories:
@@ -115,7 +125,8 @@ You can specify directories to mount into the container. They will be created on
115125

116126
## [Volumes](#volumes)
117127

118-
Any other volumes to mount, in addition to the files and directories. They are not created or copied before mounting:
128+
Any other volumes to mount, in addition to the files and directories.
129+
They are not created or copied before mounting:
119130

120131
```yaml
121132
volumes:

‎docs/configuration/aliases.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/alias.yml in the Kamal repository.
24
title: Aliases
35
---
46

‎docs/configuration/booting.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/boot.yml in the Kamal repository.
24
title: Booting
35
---
46

‎docs/configuration/builders.md

+9-4
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/builder.yml in the Kamal repository.
24
title: Builder
35
---
46

@@ -29,15 +31,17 @@ Allowed values are `amd64` and `arm64`:
2931

3032
## [Remote](#remote)
3133

32-
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.
34+
The connection string for a remote builder. If supplied, Kamal will use this
35+
for builds that do not match the local architecture of the deployment host.
3336

3437
```yaml
3538
remote: ssh://docker@docker-builder
3639
```
3740

3841
## [Local](#local)
3942

40-
If set to false, Kamal will always use the remote builder even when building the local architecture.
43+
If set to false, Kamal will always use the remote builder even when building
44+
the local architecture.
4145

4246
Defaults to true:
4347

@@ -60,7 +64,8 @@ The image is only used for registry cache and is not compatible with the Docker
6064

6165
## [Build context](#build-context)
6266

63-
If this is not set, then a local Git clone of the repo is used. This ensures a clean build with no uncommitted changes.
67+
If this is not set, then a local Git clone of the repo is used.
68+
This ensures a clean build with no uncommitted changes.
6469

6570
To use the local checkout instead, you can set the context to `.`, or a path to another directory.
6671

@@ -102,7 +107,7 @@ FROM ruby:$RUBY_VERSION-slim as base
102107

103108
## [Build secrets](#build-secrets)
104109

105-
Values are read from .kamal/secrets.
110+
Values are read from `.kamal/secrets`:
106111

107112
```yaml
108113
secrets:

‎docs/configuration/docker-registry.md

+13-5
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,15 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/registry.yml in the Kamal repository.
24
title: Registry
35
---
46

57
# Registry
68

7-
The default registry is Docker Hub, but you can change it using `registry/server`:
9+
The default registry is Docker Hub, but you can change it using `registry/server`.
810

9-
A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret in the local environment.
11+
A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret
12+
in the local environment:
1013

1114
```yaml
1215
registry:
@@ -19,7 +22,8 @@ registry:
1922
2023
## [Using AWS ECR as the container registry](#using-aws-ecr-as-the-container-registry)
2124
22-
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:
25+
You will need to have the AWS CLI installed locally for this to work.
26+
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:
2327

2428
```yaml
2529
registry:
@@ -30,7 +34,10 @@ registry:
3034

3135
## [Using GCP Artifact Registry as the container registry](#using-gcp-artifact-registry-as-the-container-registry)
3236

33-
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.
37+
To sign into Artifact Registry, you need to
38+
[create a service account](https://cloud.google.com/iam/docs/service-accounts-create#creating)
39+
and [set up roles and permissions](https://cloud.google.com/artifact-registry/docs/access-control#permissions).
40+
Normally, assigning the `roles/artifactregistry.writer` role should be sufficient.
3441

3542
Once the service account is ready, you need to generate and download a JSON key and base64 encode it:
3643

@@ -40,7 +47,8 @@ base64 -i /path/to/key.json | tr -d "\\n"
4047

4148
You'll then need to set the `KAMAL_REGISTRY_PASSWORD` secret to that value.
4249

43-
Use the environment variable as the password along with `_json_key_base64` as the username. Here’s the final configuration:
50+
Use the environment variable as the password along with `_json_key_base64` as the username.
51+
Here’s the final configuration:
4452

4553
```yaml
4654
registry:

‎docs/configuration/environment-variables.md

+14-6
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/env.yml in the Kamal repository.
24
title: Environment variables
35
---
46

57
# Environment variables
68

7-
Environment variables can be set directly in the Kamal configuration or read from `.kamal/secrets`.
9+
Environment variables can be set directly in the Kamal configuration or
10+
read from `.kamal/secrets`.
811

912
## [Reading environment variables from the configuration](#reading-environment-variables-from-the-configuration)
1013

@@ -22,11 +25,13 @@ env:
2225
2326
Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
2427

25-
If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if it exists.
28+
If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if
29+
it exists.
2630

2731
Common secrets across all destinations can be set in `.kamal/secrets-common`.
2832

29-
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.
33+
This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
34+
You can use variable or command substitution in the secrets file.
3035

3136
```shell
3237
KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
@@ -44,9 +49,11 @@ DB_PASSWORD=$(kamal secrets extract DB_PASSWORD $SECRETS)
4449

4550
If you store secrets directly in `.kamal/secrets`, ensure that it is not checked into version control.
4651

47-
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.
52+
To pass the secrets, you should list them under the `secret` key. When you do this, the
53+
other variables need to be moved under the `clear` key.
4854

49-
Unlike clear values, secrets are not passed directly to the container but are stored in an env file on the host:
55+
Unlike clear values, secrets are not passed directly to the container
56+
but are stored in an env file on the host:
5057

5158
```yaml
5259
env:
@@ -58,7 +65,8 @@ env:
5865

5966
## [Tags](#tags)
6067

61-
Tags are used to add extra env variables to specific hosts. See [Servers](../servers) for how to tag hosts.
68+
Tags are used to add extra env variables to specific hosts.
69+
See [Servers](../servers) for how to tag hosts.
6270

6371
Tags are only allowed in the top-level env configuration (i.e., not under a role-specific env).
6472

‎docs/configuration/logging.md

+2
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/logging.yml in the Kamal repository.
24
title: Custom logging configuration
35
---
46

‎docs/configuration/overview.md

+27-7
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,6 @@
11
---
2+
# This file has been generated from the Kamal source, do not edit directly.
3+
# Find the source of this file at lib/kamal/configuration/docs/configuration.yml in the Kamal repository.
24
title: Kamal Configuration
35
---
46

@@ -8,17 +10,21 @@ Configuration is read from the `config/deploy.yml`.
810

911
## [Destinations](#destinations)
1012

11-
When running commands, you can specify a destination with the `-d` flag, e.g., `kamal deploy -d staging`.
13+
When running commands, you can specify a destination with the `-d` flag,
14+
e.g., `kamal deploy -d staging`.
1215

13-
In this case, the configuration will also be read from `config/deploy.staging.yml` and merged with the base configuration.
16+
In this case, the configuration will also be read from `config/deploy.staging.yml`
17+
and merged with the base configuration.
1418

1519
## [Extensions](#extensions)
1620

1721
Kamal will not accept unrecognized keys in the configuration file.
1822

19-
However, you might want to declare a configuration block using YAML anchors and aliases to avoid repetition.
23+
However, you might want to declare a configuration block using YAML anchors
24+
and aliases to avoid repetition.
2025

21-
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.
26+
You can prefix a configuration section with `x-` to indicate that it is an
27+
extension. Kamal will ignore the extension and not raise an error.
2228

2329
## [The service name](#the-service-name)
2430

@@ -85,9 +91,14 @@ env:
8591
8692
Used for asset bridging across deployments, default to `nil`.
8793

88-
If there are changes to CSS or JS files, we may get requests for the old versions on the new container, and vice versa.
94+
If there are changes to CSS or JS files, we may get requests
95+
for the old versions on the new container, and vice versa.
8996

90-
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).
97+
To avoid 404s, we can specify an asset path.
98+
Kamal will replace that path in the container with a mapped
99+
volume containing both sets of files.
100+
This requires that file names change when the contents change
101+
(e.g., by including a hash of the contents in the name).
91102

92103
To configure this, set the path to the assets:
93104

@@ -97,7 +108,8 @@ asset_path: /path/to/assets
97108

98109
## [Hooks path](#hooks-path)
99110

100-
Path to hooks, defaults to `.kamal/hooks`. See [Hooks](/docs/hooks) for more information:
111+
Path to hooks, defaults to `.kamal/hooks`.
112+
See [Hooks](/docs/hooks) for more information:
101113

102114
```yaml
103115
hooks_path: /user_home/kamal/hooks
@@ -169,6 +181,14 @@ How long to wait for a container to drain, default 30:
169181
drain_timeout: 10
170182
```
171183

184+
## [Run directory](#run-directory)
185+
186+
Directory to store kamal runtime files in on the host, default `.kamal`:
187+
188+
```yaml
189+
run_directory: /etc/kamal
190+
```
191+
172192
## [SSH options](#ssh-options)
173193

174194
See [SSH](../ssh):

0 commit comments

Comments
 (0)