dash 2.12.0

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

@@ -0,0 +1,228 @@
+# Kamal Configuration
+#
+# 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`.
+#
+# In this case, the configuration will also be read from `config/deploy.staging.yml`
+# and merged with the base configuration.
+
+# Extensions
+#
+# Kamal will not accept unrecognized keys in the configuration file.
+#
+# However, you might want to declare a configuration block using YAML anchors
+# and aliases to avoid repetition.
+#
+# 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
+
+# The Docker image name
+#
+# The image will be pushed to the configured registry.
+image: my-image
+
+# Labels
+#
+# Additional labels to add to the container:
+labels:
+  my-label: my-value
+
+# 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:
+registry:
+  ...
+
+# Servers
+#
+# The servers to deploy to, optionally with custom roles, see kamal docs servers:
+servers:
+  ...
+
+# Environment variables
+#
+# See kamal docs env:
+env:
+  ...
+
+# Asset path
+#
+# Used for asset bridging across deployments, default to `nil`.
+#
+# If there are changes to CSS or JS files, we may get requests
+# for the old versions on the new container, and vice versa.
+#
+# 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.
+#
+# You can also specify mount options after a colon, such as `ro` for read-only
+# or `z`/`Z` for SELinux labels
+asset_path: /path/to/assets
+
+# 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
+
+# Hook output
+#
+# Hook output visibility. Can be set globally or per-hook.
+# CLI flags (`-v`, `-q`) override these settings.
+#
+# - `:quiet` - hook output is hidden
+# - `:verbose` - hook output is shown
+#
+# With no setting, hook output follows CLI verbosity flags.
+#
+# Note: Failed hooks always show output in the error message regardless of setting.
+#
+# Global setting for all hooks:
+hooks_output: :verbose
+# Or per-hook settings:
+hooks_output:
+  pre-deploy: :verbose
+  pre-build: :quiet
+
+# Secrets path
+#
+# Path to secrets, defaults to `.kamal/secrets`.
+# Kamal looks for `<secrets_path>-common` first and then `<secrets_path>`.
+# When using destinations, it instead looks for `<secrets_path>-common` first and then
+# `<secrets_path>.<destination>`. Later files override earlier ones.
+secrets_path: /user_home/kamal/secrets
+
+# Error pages
+#
+# A directory relative to the app root to find error pages for the proxy to serve.
+# Name each page after the HTTP status code it serves, e.g. 404.html, 500.html,
+# 502.html, 503.html, and 504.html.
+error_pages_path: public
+
+# Require destinations
+#
+# Whether deployments require a destination to be specified, defaults to `false`:
+require_destination: true
+
+# Primary role
+#
+# 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`:
+allow_empty_roles: false
+
+# Retain containers
+#
+# 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`:
+minimum_version: 1.3.0
+
+# Readiness delay
+#
+# 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
+
+# Stop timeout
+#
+# How long to wait for a container to stop after SIGTERM, default is
+# the drain_timeout for non-proxied roles and 10s (Docker default) for proxied roles.
+# Can be overridden per role:
+stop_timeout: 30
+
+# Run directory
+#
+# Directory to store kamal runtime files in on the host, default `.kamal`:
+run_directory: /etc/kamal
+
+# SSH options
+#
+# See kamal docs ssh:
+ssh:
+  ...
+
+# Builder options
+#
+# See kamal docs builder:
+builder:
+  ...
+
+# Accessories
+#
+# Additional services to run in Docker, see kamal docs accessory:
+accessories:
+  ...
+
+# Proxy
+#
+# Configuration for kamal-proxy, see kamal docs proxy:
+proxy:
+  ...
+
+# SSHKit
+#
+# See kamal docs sshkit:
+sshkit:
+  ...
+
+# Boot options
+#
+# See kamal docs boot:
+boot:
+  ...
+
+# Logging
+#
+# Docker logging configuration, see kamal docs logging:
+logging:
+  ...
+
+# Output
+#
+# Configure output loggers (OTel, file), see kamal docs output:
+output:
+  ...
+
+# Aliases
+#
+# Alias configuration, see kamal docs alias:
+aliases:
+  ...

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

@@ -0,0 +1,118 @@
+# Environment variables
+#
+# 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.
+env:
+  DATABASE_HOST: mysql-db1
+  DATABASE_PORT: 3306
+
+# Secrets
+#
+# Kamal uses dotenv to automatically load environment variables from the configured secrets files.
+#
+# Common secrets across all destinations can be set in `.kamal/secrets-common`. Kamal looks for
+# `.kamal/secrets-common` first, then `.kamal/secrets`, with later values overriding earlier ones.
+#
+# If you are using destinations, Kamal looks for `.kamal/secrets-common` first, then
+# `.kamal/secrets.<destination>`. The non-destination `.kamal/secrets` file is not read when a
+# destination is selected.
+#
+# 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.
+#
+# 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:
+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).
+#
+# The env variables can be specified with secret and clear values as explained above.
+env:
+  tags:
+    <tag1>:
+      MYSQL_USER: monitoring
+    <tag2>:
+      clear:
+        MYSQL_USER: readonly
+      secret:
+        - MYSQL_PASSWORD
+
+# Example configuration
+env:
+  clear:
+    MYSQL_USER: app
+  secret:
+    - MYSQL_PASSWORD
+  tags:
+    monitoring:
+      MYSQL_USER: monitoring
+    replica:
+      clear:
+        MYSQL_USER: readonly
+      secret:
+        - READONLY_PASSWORD

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

@@ -0,0 +1,21 @@
+# Custom logging configuration
+#
+# Set these to control the Docker logging driver and options.
+
+# Logging settings
+#
+# These go under the logging key in the configuration file.
+#
+# 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`:
+  driver: json-file
+
+  # Options
+  #
+  # Any logging options to pass to the driver, passed to Docker via `--log-opt`:
+  options:
+    max-size: 100m

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

@@ -0,0 +1,25 @@
+# Output
+#
+# Configure where Kamal sends command output logs.
+
+# Output options
+#
+# The options are specified under the output key in the configuration file.
+output:
+
+  # OTel
+  #
+  # Ship deploy logs to an OpenTelemetry-compatible endpoint via OTLP HTTP.
+  #
+  # Logs are sent as OTLP log records with resource attributes derived from
+  # Kamal's deploy tags (service, version, performer, destination, etc.)
+  otel:
+    endpoint: http://otel-gateway:4318
+
+  # File
+  #
+  # Write deploy logs to a file on the local machine.
+  #
+  # One log file is created per deploy, named with the timestamp and command.
+  file:
+    path: /var/log/kamal/

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

@@ -0,0 +1,207 @@
+# 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
+    
+  # Loadbalancer
+  #
+  # Specify a host to run the loadbalancer on. The loadbalancer will distribute requests
+  # to all web hosts. If not specified but multiple web hosts are configured, the first
+  # web host will be used as the loadbalancer host.
+  loadbalancer: lb.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: true
+
+  # 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 more 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. You should
+  # pass a hash mapping the `certificate_pem` and `private_key_pem` to the secret names.
+  ssl:
+    certificate_pem: CERTIFICATE_PEM
+    private_key_pem: PRIVATE_KEY_PEM
+  # ### Notes
+  # - If the certificate or key is missing or invalid, deployments will fail.
+  # - Always handle SSL certificates and private keys securely. Avoid hard-coding them in source control.
+
+  # 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.
+  # Usage sample: path_prefix: '/api'
+  #
+  # You can also specify multiple paths in two ways.
+  #
+  # When using path_prefix you can supply multiple routes separated by commas.
+  path_prefix: "/api,/oauth_callback"
+  # You can also specify paths as a list of paths, the configuration will be
+  # rolled together into a comma separated string.
+  path_prefixes:
+    - "/api"
+    - "/oauth_callback"
+  # 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
+
+  # Run configuration
+  #
+  # These options are used when booting the proxy container.
+  #
+  run:
+    http_port: 8080                # HTTP port to use (default 80)
+    https_port: 8443               # HTTPS port to use (default 443)
+    metrics_port: 9090             # Port for Prometheus metrics
+    debug: true                    # Debug logging (default: false)
+    log_max_size: "30m"            # Maximum log file size (default: "10m")
+    publish: false                 # Publish ports to the host (default: true)
+    bind_ips:                      # List of IPs to bind to when publishing ports
+      - 0.0.0.0
+    registry: registry:4443        # Container registry for the kamal-proxy image
+                                   # (defaults to Docker Hub)
+    repository: myrepo/kamal-proxy # Container repository for the kamal-proxy image
+                                   # (defaults to `ghcr.io/mhenrixon/kamal-proxy`)
+    version: v0.8.0                # Version tag of the kamal-proxy image to use
+    options:                       # Additional options to pass to `docker run`
+      label:
+        - custom.label=kamal-proxy
+      memory: 512m
+      cpus: 0.5
+
+# 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
+# ```

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

@@ -0,0 +1,64 @@
+# Registry
+#
+# The default registry is Docker Hub, but you can change it using `registry/server`.
+
+# Using a local container registry
+#
+# If the registry server starts with `localhost`, Kamal will start a local Docker registry
+# on that port and push the app image to it.
+registry:
+  server: localhost:5555
+
+# Using Docker Hub as the container registry
+#
+# 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, `KAMAL_REGISTRY_PASSWORD`) will look up the secret
+# in the local environment:
+registry:
+  username:
+    - <your docker hub username>
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+# 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 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:
+registry:
+  server: <your aws account id>.dkr.ecr.<your aws region id>.amazonaws.com
+  username: AWS
+  password: <%= %x(aws ecr get-login-password) %>
+
+# Using GCP Artifact Registry as the container registry
+#
+# 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"
+# ```
+#
+# You'll then need to set the `KAMAL_REGISTRY_PASSWORD` secret to that value.
+#
+# Use the environment variable as the password along with `_json_key_base64` as the username.
+# Here’s the final configuration:
+registry:
+  server: <your registry region>-docker.pkg.dev
+  username: _json_key_base64
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+# Validating the configuration
+#
+# You can validate the configuration by running:
+#
+# ```shell
+# kamal registry login
+# ```