From 68fc95bea4cb1cd339b56f0af24b8c5251921fd9 Mon Sep 17 00:00:00 2001 From: Ralf Schmitz Bongiolo Date: Fri, 11 Oct 2024 08:13:34 -0400 Subject: [PATCH 01/11] feat(secrets): document Doppler adapter usage --- docs/commands/secrets.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md index 188d03d..17bba2f 100644 --- a/docs/commands/secrets.md +++ b/docs/commands/secrets.md @@ -90,3 +90,22 @@ kamal secrets fetch --adapter bitwarden --account email@example.com MyItem/REGIS kamal secrets extract REGISTRY_PASSWORD kamal secrets extract MyItem/REGISTRY_PASSWORD ``` + +## Doppler + +First, install and configure [the Doppler CLI](https://docs.doppler.com/docs/install-cli). + +Use the adapter `doppler`: + +```bash +# Fetch passwords +kamal secrets fetch --adapter doppler --account my-project/prd REGISTRY_PASSWORD DB_PASSWORD + +# Extract the secret +kamal secrets extract REGISTRY_PASSWORD +kamal secrets extract DB_PASSWORD +``` + +Doppler organizes secrets in "projects" (like `my-awesome-project`) and "configs" (like `prod`, `stg`, etc), use the pattern `project/config` when defining the `--account` option. + +Doppler does not have a concept of folders, so using `--from` option or `FOLDER/SECRET` pattern is not supported and will raise an error. From 1ee13552d3d45660408751327d242bc467f0af3b Mon Sep 17 00:00:00 2001 From: Justin Dell Date: Mon, 21 Oct 2024 09:23:56 -0500 Subject: [PATCH 02/11] documentation for aws secrets manager --- docs/commands/secrets.md | 23 +++++++++++++++++++++++ 1 file changed, 23 insertions(+) diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md index 494bdb2..eabba46 100644 --- a/docs/commands/secrets.md +++ b/docs/commands/secrets.md @@ -94,3 +94,26 @@ kamal secrets fetch --adapter bitwarden --account email@example.com MyItem/REGIS kamal secrets extract REGISTRY_PASSWORD kamal secrets extract MyItem/REGISTRY_PASSWORD ``` + +## AWS Secrets Manager + +First, install and configure [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). + +Use the adapter `aws_secretsmanager`: + +```bash +# Fetch passwords +kamal secrets fetch --adapter aws_secretsmanager --account default REGISTRY_PASSWORD DB_PASSWORD + +# Fetch passwords from an item +kamal secrets fetch --adapter bitwarden --account default --from myapp/ REGISTRY_PASSWORD DB_PASSWORD + +# Fetch passwords from multiple items +kamal secrets fetch --adapter bitwarden --account default myapp/REGISTRY_PASSWORD myapp/DB_PASSWORD + +# Extract the secret +kamal secrets extract REGISTRY_PASSWORD +kamal secrets extract MyItem/REGISTRY_PASSWORD +``` + +**Note:** The `--account` option should be set to your AWS CLI profile name, which is typically `default`. Ensure that your AWS CLI is configured with the necessary permissions to access AWS Secrets Manager. From cea89353760db0e01b176aaf13a9ac4a2435cfb7 Mon Sep 17 00:00:00 2001 From: rameerez <4920956+rameerez@users.noreply.github.com> Date: Thu, 24 Oct 2024 18:04:27 +0200 Subject: [PATCH 03/11] Update proxy.md Add a small note that enabling `ssl: true` makes `kamal-proxy` stop forwarding headers unless `forward_headers` is also set to `true` --- docs/configuration/proxy.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/configuration/proxy.md b/docs/configuration/proxy.md index 42dab4d..0ccb2f3 100644 --- a/docs/configuration/proxy.md +++ b/docs/configuration/proxy.md @@ -67,6 +67,8 @@ Defaults to `false`: ssl: true ``` +If you set `ssl` to `true`, `kamal-proxy` will stop forwarding headers to your app, unless you explicitly set `forward_headers: true`, as documented in [Forward Headers](#forward-headers). + ## [Response timeout](#response-timeout) How long to wait for requests to complete before timing out, defaults to 30 seconds: From c5e72d36323a0e07a0c414ed7d3c6d564eb45756 Mon Sep 17 00:00:00 2001 From: Justin Dell Date: Mon, 4 Nov 2024 09:48:15 -0600 Subject: [PATCH 04/11] rename aws_secretsmanager to aws_secrets_manager --- docs/commands/secrets.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md index eabba46..d5d50c3 100644 --- a/docs/commands/secrets.md +++ b/docs/commands/secrets.md @@ -99,17 +99,17 @@ kamal secrets extract MyItem/REGISTRY_PASSWORD First, install and configure [the AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html). -Use the adapter `aws_secretsmanager`: +Use the adapter `aws_secrets_manager`: ```bash # Fetch passwords -kamal secrets fetch --adapter aws_secretsmanager --account default REGISTRY_PASSWORD DB_PASSWORD +kamal secrets fetch --adapter aws_secrets_manager --account default REGISTRY_PASSWORD DB_PASSWORD # Fetch passwords from an item -kamal secrets fetch --adapter bitwarden --account default --from myapp/ REGISTRY_PASSWORD DB_PASSWORD +kamal secrets fetch --adapter aws_secrets_manager --account default --from myapp/ REGISTRY_PASSWORD DB_PASSWORD # Fetch passwords from multiple items -kamal secrets fetch --adapter bitwarden --account default myapp/REGISTRY_PASSWORD myapp/DB_PASSWORD +kamal secrets fetch --adapter aws_secrets_manager --account default myapp/REGISTRY_PASSWORD myapp/DB_PASSWORD # Extract the secret kamal secrets extract REGISTRY_PASSWORD From 7b784c6837ca98cd851413008492bcd7d1b771ad Mon Sep 17 00:00:00 2001 From: Luca Marturana Date: Tue, 5 Nov 2024 10:08:45 +0100 Subject: [PATCH 05/11] Update cron.md Copy env variables when installing crontab --- docs/configuration/cron.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuration/cron.md b/docs/configuration/cron.md index d285312..1deae05 100644 --- a/docs/configuration/cron.md +++ b/docs/configuration/cron.md @@ -12,7 +12,7 @@ servers: hosts: - 192.168.0.1 cmd: - bash -c "cat config/crontab | crontab - && cron -f" + bash -c "(env && cat config/crontab) | crontab - && cron -f" ``` -This assumes that the Cron settings are stored in `config/crontab`. +This assumes that the Cron settings are stored in `config/crontab`. Cron does not automatically propagate environment variables, the example above copies them into the crontab. From 4554ddfb8096176785556fd37c94a64266199e27 Mon Sep 17 00:00:00 2001 From: Igor Alexandrov Date: Sun, 10 Nov 2024 22:05:35 +0400 Subject: [PATCH 06/11] Fixed type in naming Traefik's EntryPoint as an Endpoint --- docs/upgrading/proxy-changes.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/upgrading/proxy-changes.md b/docs/upgrading/proxy-changes.md index c7f69e2..da6e5b4 100644 --- a/docs/upgrading/proxy-changes.md +++ b/docs/upgrading/proxy-changes.md @@ -32,7 +32,7 @@ These use cases were unsupported and error-prone, though, and we wanted to provi ### 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, EntryPoints. 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 From 535ae4580bea666f410ffa706ef03d512802ea20 Mon Sep 17 00:00:00 2001 From: Ralf Schmitz Bongiolo Date: Thu, 21 Nov 2024 20:06:37 -0400 Subject: [PATCH 07/11] Adjust doppler documentation --- docs/commands/secrets.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/commands/secrets.md b/docs/commands/secrets.md index 17bba2f..0bbade2 100644 --- a/docs/commands/secrets.md +++ b/docs/commands/secrets.md @@ -99,13 +99,16 @@ Use the adapter `doppler`: ```bash # Fetch passwords -kamal secrets fetch --adapter doppler --account my-project/prd REGISTRY_PASSWORD DB_PASSWORD +kamal secrets fetch --adapter doppler --from my-project/prd REGISTRY_PASSWORD DB_PASSWORD + +# The project/config pattern is also supported in this way +kamal secrets fetch --adapter doppler my-project/prd/REGISTRY_PASSWORD my-project/prd/DB_PASSWORD # Extract the secret kamal secrets extract REGISTRY_PASSWORD kamal secrets extract DB_PASSWORD ``` -Doppler organizes secrets in "projects" (like `my-awesome-project`) and "configs" (like `prod`, `stg`, etc), use the pattern `project/config` when defining the `--account` option. +Doppler organizes secrets in "projects" (like `my-awesome-project`) and "configs" (like `prod`, `stg`, etc), use the pattern `project/config` when defining the `--from` option. -Doppler does not have a concept of folders, so using `--from` option or `FOLDER/SECRET` pattern is not supported and will raise an error. +The doppler adapter does not use the `--account` option, if given it will be ignored. From dad380daec8bf75cdc40b34928bf2e66d7ae6330 Mon Sep 17 00:00:00 2001 From: Nick Hammond Date: Wed, 4 Dec 2024 08:45:11 -0700 Subject: [PATCH 08/11] Add bin/dev script --- _config.yml | 1 + bin/dev | 4 ++++ 2 files changed, 5 insertions(+) create mode 100755 bin/dev diff --git a/_config.yml b/_config.yml index bb50b95..bdb7826 100644 --- a/_config.yml +++ b/_config.yml @@ -16,6 +16,7 @@ exclude: - Gemfile - Gemfile.lock - README.md + - bin sass: style: compressed diff --git a/bin/dev b/bin/dev new file mode 100755 index 0000000..ee8e8fd --- /dev/null +++ b/bin/dev @@ -0,0 +1,4 @@ +#!/usr/bin/env sh + +bundle install +bundle exec jekyll serve --livereload From a316aea9b50d3e972ac66e166fd944dde2f32b95 Mon Sep 17 00:00:00 2001 From: Nick Hammond Date: Fri, 6 Dec 2024 07:50:05 -0700 Subject: [PATCH 09/11] Mention docker-options for proxy boot config --- docs/commands/proxy.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/commands/proxy.md b/docs/commands/proxy.md index 7c49d52..fadf6fe 100644 --- a/docs/commands/proxy.md +++ b/docs/commands/proxy.md @@ -45,6 +45,7 @@ Options: # Default: 443 [--log-max-size=LOG_MAX_SIZE] # Max size of proxy logs # Default: 10m + [--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. From 4416be3fc5a8ac11454ec276f990a45109f084d5 Mon Sep 17 00:00:00 2001 From: Donal McBreen Date: Fri, 13 Dec 2024 12:37:23 +0000 Subject: [PATCH 10/11] Update docs and version --- _data/github.yml | 2 +- _data/nav.yml | 2 +- docs/commands/version.md | 2 +- docs/configuration/accessories.md | 12 +++++++++-- docs/configuration/aliases.md | 2 +- docs/configuration/builders.md | 9 +++++++++ docs/configuration/docker-registry.md | 4 +++- docs/configuration/proxy.md | 29 ++++++++++++++------------- 8 files changed, 41 insertions(+), 21 deletions(-) diff --git a/_data/github.yml b/_data/github.yml index 4869346..21ddac4 100644 --- a/_data/github.yml +++ b/_data/github.yml @@ -1,3 +1,3 @@ -tag_name: 2.3.0 +tag_name: 2.4.0 v1: tag_name: 1.9.2 diff --git a/_data/nav.yml b/_data/nav.yml index 4b16529..d25cc0f 100644 --- a/_data/nav.yml +++ b/_data/nav.yml @@ -1,7 +1,7 @@ - title: "Documentation" url: /docs/ options: - - title: "Version 2.3.0" + - title: "Version 2.4.0" url: /docs/ - title: "Version 1.9.2" url: /v1/docs/ diff --git a/docs/commands/version.md b/docs/commands/version.md index 283dd27..0a42886 100644 --- a/docs/commands/version.md +++ b/docs/commands/version.md @@ -8,5 +8,5 @@ Returns the version of Kamal you have installed. ```bash $ kamal version -2.3.0 +2.4.0 ``` diff --git a/docs/configuration/accessories.md b/docs/configuration/accessories.md index 249bbd5..a9d21c4 100644 --- a/docs/configuration/accessories.md +++ b/docs/configuration/accessories.md @@ -64,8 +64,8 @@ You can set a custom command to run in the container if you do not want to use t ## [Port mappings](#port-mappings) -See [https://docs.docker.com/network/](https://docs.docker.com/network/), and especially note the warning about the security -implications of exposing ports publicly. +See [https://docs.docker.com/network/](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" @@ -142,3 +142,11 @@ Defaults to kamal: ```yaml network: custom ``` + +## [Proxy](#proxy) + + +```yaml + proxy: + ... +``` diff --git a/docs/configuration/aliases.md b/docs/configuration/aliases.md index 04cf851..8739cfe 100644 --- a/docs/configuration/aliases.md +++ b/docs/configuration/aliases.md @@ -18,7 +18,7 @@ By defining an alias, like this: ```yaml aliases: - console: app exec --reuse -i "bin/rails console" + console: app exec -i --reuse "bin/rails console" ``` You can now open the console with: diff --git a/docs/configuration/builders.md b/docs/configuration/builders.md index e270e42..358915a 100644 --- a/docs/configuration/builders.md +++ b/docs/configuration/builders.md @@ -153,3 +153,12 @@ The value can also be a boolean to enable or disable provenance attestations. ```yaml provenance: mode=max ``` + +## [SBOM (Software Bill of Materials)](#sbom-(software-bill-of-materials)) + +It is used to configure SBOM generation for the build result. +The value can also be a boolean to enable or disable SBOM generation. + +```yaml + sbom: true +``` diff --git a/docs/configuration/docker-registry.md b/docs/configuration/docker-registry.md index 87c58b7..851f285 100644 --- a/docs/configuration/docker-registry.md +++ b/docs/configuration/docker-registry.md @@ -8,7 +8,9 @@ title: Registry The default registry is Docker Hub, but you can change it using `registry/server`. -By default, Docker Hub creates public repositories. To avoid making your images public, set up a private repository before deploying, or change the default repository privacy settings to private in your [Docker Hub settings](https://hub.docker.com/repository-settings/default-privacy). +By default, Docker Hub creates public repositories. To avoid making your images public, +set up a private repository before deploying, or change the default repository privacy +settings to private in your [Docker Hub settings](https://hub.docker.com/repository-settings/default-privacy). A reference to a secret (in this case, `DOCKER_REGISTRY_TOKEN`) will look up the secret in the local environment: diff --git a/docs/configuration/proxy.md b/docs/configuration/proxy.md index 0ccb2f3..07c00c2 100644 --- a/docs/configuration/proxy.md +++ b/docs/configuration/proxy.md @@ -61,13 +61,27 @@ 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. +If you set `ssl` to `true`, `kamal-proxy` will stop forwarding headers to your app, +unless you explicitly set `forward_headers: true` + Defaults to `false`: ```yaml ssl: true ``` -If you set `ssl` to `true`, `kamal-proxy` will stop forwarding headers to your app, unless you explicitly set `forward_headers: true`, as documented in [Forward Headers](#forward-headers). +## [Forward headers](#forward-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. + +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 +``` ## [Response timeout](#response-timeout) @@ -125,16 +139,3 @@ By default, `Cache-Control`, `Last-Modified`, and `User-Agent` request headers a - X-Request-ID - X-Request-Start ``` - -## [Forward headers](#forward-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. - -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 -``` From afe03630bcbde2693b3bb5148e09c879d0136058 Mon Sep 17 00:00:00 2001 From: Donal McBreen Date: Fri, 13 Dec 2024 12:46:35 +0000 Subject: [PATCH 11/11] Add link to proxy docs from accessory --- docs/configuration/accessories.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/configuration/accessories.md b/docs/configuration/accessories.md index a9d21c4..90f4d03 100644 --- a/docs/configuration/accessories.md +++ b/docs/configuration/accessories.md @@ -145,6 +145,7 @@ Defaults to kamal: ## [Proxy](#proxy) +You can run your accessory behind the Kamal proxy. See [Proxy](../proxy) for more information. ```yaml proxy: