kamal 1.8.3 → 2.7.0

data/lib/kamal/configuration/docs/builder.yml

@@ -1,47 +1,54 @@
 # Builder
 #
-# The builder configuration controls how the application is built with `docker build` or `docker buildx build`
+# The builder configuration controls how the application is built with `docker build`.
 #
-# If no configuration is specified, Kamal will:
-# 1. Create a buildx context called `kamal-<service>-multiarch`
-# 2. Use `docker buildx build` to build a multiarch image for linux/amd64,linux/arm64 with that context
-#
-# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information
+# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information.
 
 # Builder options
 #
 # Options go under the builder key in the root configuration.
 builder:
 
-  # Multiarch
+  # Arch
   #
-  # Enables multiarch builds, defaults to `true`
-  multiarch: false
-
-  # Local configuration
+  # The architectures to build for — you can set an array or just a single value.
   #
-  # The build configuration for local builds, only used if multiarch is enabled (the default)
+  # Allowed values are `amd64` and `arm64`:
+  arch:
+    - amd64
+
+  # Remote
   #
-  # If there is no remote configuration, by default we build for amd64 and arm64.
-  # If you only want to build for one architecture, you can specify it here.
-  # The docker socket is optional and uses the default docker host socket when not specified
-  local:
-    arch: amd64
-    host: /var/run/docker.sock
+  # 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.
+  remote: ssh://docker@docker-builder
 
-  # Remote configuration
+  # Local
+  #
+  # If set to false, Kamal will always use the remote builder even when building
+  # the local architecture.
   #
-  # The build configuration for remote builds, also only used if multiarch is enabled.
-  # The arch is required and can be either amd64 or arm64.
-  remote:
-    arch: arm64
-    host: ssh://docker@docker-builder
+  # Defaults to true:
+  local: true
+
+  # Buildpack configuration
+  #
+  # The build configuration for using pack to build a Cloud Native Buildpack image.
+  #
+  # For additional buildpack customization options you can create a project descriptor
+  # file(project.toml) that the Pack CLI will automatically use.
+  # See https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/use-project-toml/ for more information.
+  pack:
+    builder: heroku/builder:24
+    buildpacks:
+      - heroku/ruby
+      - heroku/procfile
 
   # Builder cache
   #
-  # The type must be either 'gha' or 'registry'
+  # The type must be either 'gha' or 'registry'.
   #
-  # The image is only used for registry cache
+  # The image is only used for registry cache and is not compatible with the Docker driver:
   cache:
     type: registry
     options: mode=max
@@ -49,25 +56,25 @@ builder:
 
   # Build context
   #
-  # If this is not set, then a local git clone of the repo is used.
+  # 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.
   context: .
 
   # Dockerfile
   #
-  # The Dockerfile to use for building, defaults to `Dockerfile`
+  # The Dockerfile to use for building, defaults to `Dockerfile`:
   dockerfile: Dockerfile.production
 
   # Build target
   #
-  # If not set, then the default target is used
+  # If not set, then the default target is used:
   target: production
 
-  # Build Arguments
+  # Build arguments
   #
-  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`
+  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`:
   args:
     ENVIRONMENT: production
 
@@ -80,28 +87,46 @@ builder:
 
   # Build secrets
   #
-  # Values are read from the environment.
-  #
+  # Values are read from `.kamal/secrets`:
   secrets:
     - SECRET1
     - SECRET2
 
-  # Referencing Build Secrets
+  # Referencing build secrets
   #
   # ```shell
   # # Copy Gemfiles
   # 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 && \
   #   rm -rf /usr/local/bundle/cache
   # ```
 
-
   # SSH
   #
-  # SSH agent socket or keys to expose to the build
+  # SSH agent socket or keys to expose to the build:
   ssh: default=$SSH_AUTH_SOCK
+
+  # Driver
+  #
+  # The build driver to use, defaults to `docker-container`:
+  driver: docker
+  #
+  # If you want to use Docker Build Cloud (https://www.docker.com/products/build-cloud/), you can set the driver to:
+  driver: cloud org-name/builder-name
+
+  # Provenance
+  #
+  # It is used to configure provenance attestations for the build result.
+  # The value can also be a boolean to enable or disable provenance attestations.
+  provenance: mode=max
+
+  # 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.
+  sbom: true

data/lib/kamal/configuration/docs/configuration.yml

@@ -1,14 +1,13 @@
 # Kamal Configuration
 #
-# Configuration is read from the `config/deploy.yml`
-#
+# Configuration is read from the `config/deploy.yml`.
 
 # Destinations
 #
 # When running commands, you can specify a destination with the `-d` flag,
-# e.g. `kamal deploy -d staging`
+# e.g., `kamal deploy -d staging`.
 #
-# In this case the configuration will also be read from `config/deploy.staging.yml`
+# In this case, the configuration will also be read from `config/deploy.staging.yml`
 # and merged with the base configuration.
 
 # Extensions
@@ -18,10 +17,11 @@
 # 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
+# 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
+#
 # This is a required value. It is used as the container name prefix.
 service: myapp
 
@@ -32,137 +32,153 @@ image: my-image
 
 # Labels
 #
-# Additional labels to add to the container
+# Additional labels to add to the container:
 labels:
   my-label: my-value
 
-# Additional volumes to mount into the container
+# Volumes
+#
+# Additional volumes to mount into the container:
 volumes:
   - /path/on/host:/path/in/container:ro
 
 # Registry
 #
-# The Docker registry configuration, see kamal docs registry
+# The Docker registry configuration, see kamal docs registry:
 registry:
   ...
 
 # Servers
 #
-# The servers to deploy to, optionally with custom roles, see kamal docs servers
+# The servers to deploy to, optionally with custom roles, see kamal docs servers:
 servers:
   ...
 
 # Environment variables
 #
-# See kamal docs env
+# See kamal docs env:
 env:
   ...
 
-# Asset Bridging
+# Asset path
 #
-# Used for asset bridging across deployments, default to `nil`
+# Used for asset bridging across deployments, default to `nil`.
 #
 # If there are changes to CSS or JS files, we may get requests
-# for the old versions on the new container and vice-versa.
+# for the old versions on the new container, and vice versa.
 #
-# To avoid 404s we can specify an asset path.
+# 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).
-
+# (e.g., by including a hash of the contents in the name).
+#
 # To configure this, set the path to the assets:
 asset_path: /path/to/assets
 
-# Path to hooks, defaults to `.kamal/hooks`
-# See https://kamal-deploy.org/docs/hooks for more information
+# Hooks path
+#
+# Path to hooks, defaults to `.kamal/hooks`.
+# See https://kamal-deploy.org/docs/hooks for more information:
 hooks_path: /user_home/kamal/hooks
 
+# Error pages
+#
+# A directory relative to the app root to find error pages for the proxy to serve.
+# Any files in the format 4xx.html or 5xx.html will be copied to the hosts.
+error_pages_path: public
+
 # Require destinations
 #
-# Whether deployments require a destination to be specified, defaults to `false`
+# Whether deployments require a destination to be specified, defaults to `false`:
 require_destination: true
 
-# The primary role
+# Primary role
 #
-# This defaults to `web`, but if you have no web role, you can change this
+# This defaults to `web`, but if you have no web role, you can change this:
 primary_role: workers
 
 # Allowing empty roles
 #
-# Whether roles with no servers are allowed. Defaults to `false`.
+# Whether roles with no servers are allowed. Defaults to `false`:
 allow_empty_roles: false
 
-# Stop wait time
-#
-# How long we wait for a container to stop before killing it, defaults to 30 seconds
-stop_wait_time: 60
-
 # Retain containers
 #
-# How many old containers and images we retain, defaults to 5
+# How many old containers and images we retain, defaults to 5:
 retain_containers: 3
 
 # 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`:
 minimum_version: 1.3.0
 
 # Readiness delay
 #
-# Seconds to wait for a container to boot after is running, default 7
-# This only applies to containers that do not specify a healthcheck
+# Seconds to wait for a container to boot after it is running, default 7.
+#
+# This only applies to containers that do not run a proxy or specify a healthcheck:
 readiness_delay: 4
 
+# Deploy timeout
+#
+# How long to wait for a container to become ready, default 30:
+deploy_timeout: 10
+
+# Drain timeout
+#
+# How long to wait for a container to drain, default 30:
+drain_timeout: 10
+
 # Run directory
 #
-# Directory to store kamal runtime files in on the host, default `.kamal`
+# Directory to store kamal runtime files in on the host, default `.kamal`:
 run_directory: /etc/kamal
 
 # SSH options
 #
-# See kamal docs ssh
+# See kamal docs ssh:
 ssh:
   ...
 
 # Builder options
 #
-# See kamal docs builder
+# See kamal docs builder:
 builder:
   ...
 
 # Accessories
 #
-# Additionals services to run in Docker, see kamal docs accessory
+# Additional services to run in Docker, see kamal docs accessory:
 accessories:
   ...
 
-# Traefik
+# Proxy
 #
-# The Traefik proxy is used for zero-downtime deployments, see kamal docs traefik
-traefik:
+# Configuration for kamal-proxy, see kamal docs proxy:
+proxy:
   ...
 
 # SSHKit
 #
-# See kamal docs sshkit
+# See kamal docs sshkit:
 sshkit:
   ...
 
 # Boot options
 #
-# See kamal docs boot
+# See kamal docs boot:
 boot:
   ...
 
-# Healthcheck
+# Logging
 #
-# Configuring healthcheck commands, intervals and timeouts, see kamal docs healthcheck
-healthcheck:
+# Docker logging configuration, see kamal docs logging:
+logging:
   ...
 
-# Logging
+# Aliases
 #
-# Docker logging configuration, see kamal docs logging
-logging:
+# Alias configuration, see kamal docs alias:
+aliases:
   ...

data/lib/kamal/configuration/docs/env.yml

@@ -1,49 +1,93 @@
 # Environment variables
 #
-# Environment variables can be set directory in the Kamal configuration or
-# for loaded from a .env file, for secrets that should not be checked into Git.
+# Environment variables can be set directly in the Kamal configuration or
+# read from `.kamal/secrets`.
 
 # 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.
 env:
   DATABASE_HOST: mysql-db1
   DATABASE_PORT: 3306
 
-# Using .env file to load required environment variables
+# Secrets
 #
-# Kamal uses dotenv to automatically load environment variables set in the .env file present
-# in the application root.
+# Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
 #
-# This file can be used to set variables like KAMAL_REGISTRY_PASSWORD or database passwords.
-# But for this reason you must ensure that .env files are not checked into Git or included
-# in your Dockerfile! The format is just key-value like:
+# If you are using destinations, secrets will instead be read from `.kamal/secrets.<DESTINATION>` if
+# it exists.
+#
+# Common secrets across all destinations can be set in `.kamal/secrets-common`.
+#
+# This file can be used to set variables like `KAMAL_REGISTRY_PASSWORD` or database passwords.
+# You can use variable or command substitution in the secrets file.
+#
+# ```shell
+# KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD
+# RAILS_MASTER_KEY=$(cat config/master.key)
 # ```
-# KAMAL_REGISTRY_PASSWORD=pw
-# DB_PASSWORD=secret123
+#
+# 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)
 # ```
-# See https://kamal-deploy.org/docs/commands/envify/ for how to use generated .env files.
 #
-# To pass the secrets you should list them under the `secret` key. When you do this the
+# 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.
 #
-# Unlike clear values, secrets are not passed directly to the container,
-# but are stored in an env file on the host
-# The file is not updated when deploying, only when running `kamal envify` or `kamal env push`.
+# Unlike clear values, secrets are not passed directly to the container
+# but are stored in an env file on the host:
 env:
   clear:
     DB_USER: app
   secret:
     - DB_PASSWORD
 
+# Aliased secrets
+#
+# You can also alias secrets to other secrets using a `:` separator.
+#
+# This is useful when the ENV name is different from the secret name. For example, if you have two
+# places where you need to define the ENV variable `DB_PASSWORD`, but the value is different depending
+# on the context.
+#
+# ```shell
+# SECRETS=$(kamal secrets fetch ...)
+#
+# MAIN_DB_PASSWORD=$(kamal secrets extract MAIN_DB_PASSWORD $SECRETS)
+# SECONDARY_DB_PASSWORD=$(kamal secrets extract SECONDARY_DB_PASSWORD $SECRETS)
+# ```
+env:
+  secret:
+    - DB_PASSWORD:MAIN_DB_PASSWORD
+  tags:
+    secondary_db:
+      secret:
+        - DB_PASSWORD:SECONDARY_DB_PASSWORD
+accessories:
+  main_db_accessory:
+    env:
+      secret:
+        - DB_PASSWORD:MAIN_DB_PASSWORD
+  secondary_db_accessory:
+    env:
+      secret:
+        - DB_PASSWORD:SECONDARY_DB_PASSWORD
+
 # Tags
 #
 # Tags are used to add extra env variables to specific hosts.
 # See kamal docs 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.
 env:

data/lib/kamal/configuration/docs/logging.yml

@@ -6,16 +6,16 @@
 #
 # 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.
 logging:
 
   # Driver
   #
-  # The logging driver to use, passed to Docker via `--log-driver`
+  # The logging driver to use, passed to Docker via `--log-driver`:
   driver: json-file
 
   # Options
   #
-  # Any logging options to pass to the driver, passed to Docker via `--log-opt`
+  # Any logging options to pass to the driver, passed to Docker via `--log-opt`:
   options:
     max-size: 100m

data/lib/kamal/configuration/docs/proxy.yml

@@ -0,0 +1,168 @@
+# 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.
+#
+# They are application-specific, so they are not shared when multiple applications
+# run on the same proxy.
+#
+proxy:
+
+  # Hosts
+  #
+  # The hosts that will be used to serve the app. The proxy will only route requests
+  # to this host to your app.
+  #
+  # If no hosts are set, then all requests will be forwarded, except for matching
+  # requests for other apps deployed on that server that do have a host set.
+  #
+  # Specify one of `host` or `hosts`.
+  host: foo.example.com
+  hosts:
+    - foo.example.com
+    - bar.example.com
+
+  # App port
+  #
+  # The port the application container is exposed on.
+  #
+  # Defaults to 80:
+  app_port: 3000
+
+  # SSL
+  #
+  # kamal-proxy can provide automatic HTTPS for your application via Let's Encrypt.
+  #
+  # 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`:
+  ssl: ...
+
+  # Custom SSL certificate
+  #
+  # In some cases, using Let's Encrypt for automatic certificate management is not an
+  # option, for example if you are running from host than one host. Or you may already
+  # have SSL certificates issued by a different Certificate Authority (CA).
+  # Kamal supports loading custom SSL certificates
+  # directly from secrets.
+  #
+  # Examples:
+  #   ssl: true              # Enable SSL with Let's Encrypt
+  #   ssl: false             # Disable SSL
+  #   ssl:                   # Enable custom SSL
+  #     certificate_pem: CERTIFICATE_PEM
+  #     private_key_pem: PRIVATE_KEY_PEM
+  #
+  # ### Notes
+  # - If the certificate or key is missing or invalid, kamal-proxy will fail to start.
+  # - Always handle SSL certificates and private keys securely. Avoid hard-coding them in deploy.yml files or source control.
+  # - For automated certificate management, consider using the built-in Let's Encrypt integration instead.
+
+  # SSL redirect
+  #
+  # By default, kamal-proxy will redirect all HTTP requests to HTTPS when SSL is enabled.
+  # If you prefer that HTTP traffic is passed through to your application (along with
+  # HTTPS traffic), you can disable this redirect by setting `ssl_redirect: false`:
+  ssl_redirect: false
+
+  # 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`.
+  forward_headers: true
+
+  # Response timeout
+  #
+  # How long to wait for requests to complete before timing out, defaults to 30 seconds:
+  response_timeout: 10
+
+  # Path-based routing
+  #
+  # For applications that split their traffic to different services based on the request path,
+  # you can use path-based routing to mount services under different path prefixes.
+  path_prefix: '/api'
+  # By default, the path prefix will be stripped from the request before it is forwarded upstream.
+  # So in the example above, a request to /api/users/123 will be forwarded to web-1 as /users/123.
+  # To instead forward the request with the original path (including the prefix),
+  # specify --strip-path-prefix=false
+  strip_path_prefix: false
+
+  # 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.
+  #
+  # Once the app is up, the proxy will stop hitting the healthcheck endpoint.
+  healthcheck:
+    interval: 3
+    path: /health
+    timeout: 3
+
+  # Buffering
+  #
+  # 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.
+  #
+  # You can also set the memory limit for buffering, which defaults to 1MB; anything
+  # larger than that is written to disk.
+  buffering:
+    requests: true
+    responses: true
+    max_request_body: 40_000_000
+    max_response_body: 0
+    memory: 2_000_000
+
+  # 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:
+  logging:
+    request_headers:
+      - Cache-Control
+      - X-Forwarded-Proto
+    response_headers:
+      - X-Request-ID
+      - X-Request-Start
+
+# Enabling/disabling the proxy on roles
+#
+# The proxy is enabled by default on the primary role but can be disabled by
+# setting `proxy: false` in the primary role's configuration.
+#
+# ```yaml
+# servers:
+#   web:
+#     hosts:
+#      - ...
+#     proxy: false
+# ```
+#
+# It is disabled by default on all other roles but can be enabled by setting
+# `proxy: true` or providing a proxy configuration for that role.
+#
+# ```yaml
+# servers:
+#   web:
+#     hosts:
+#      - ...
+#   web2:
+#     hosts:
+#      - ...
+#     proxy: true
+# ```