kamal 2.7.0 → 2.11.0

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

@@ -73,7 +73,10 @@ env:
 # 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:
+# 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
@@ -82,6 +85,32 @@ asset_path: /path/to/assets
 # 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 will look for `<secrets_path>-common` and `<secrets_path>` (or `<secrets_path>.<destination>` when using destinations):
+secrets_path: /user_home/kamal/secrets
+
 # Error pages
 #
 # A directory relative to the app root to find error pages for the proxy to serve.

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

@@ -45,27 +45,23 @@ proxy:
   # unless you explicitly set `forward_headers: true`
   #
   # Defaults to `false`:
-  ssl: ...
+  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 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
+  # 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, 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.
+  # - 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
   #
@@ -93,9 +89,21 @@ proxy:
   #
   # 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'
+  # 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
@@ -140,6 +148,30 @@ proxy:
       - 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 `basecamp/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

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

@@ -1,19 +1,27 @@
 # 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, `DOCKER_REGISTRY_TOKEN`) will look up the secret
+# A reference to a secret (in this case, `KAMAL_REGISTRY_PASSWORD`) will look up the secret
 # in the local environment:
 registry:
-  server: registry.digitalocean.com
   username:
-    - DOCKER_REGISTRY_TOKEN
+    - <your docker hub username>
   password:
-    - DOCKER_REGISTRY_TOKEN
+    - KAMAL_REGISTRY_PASSWORD
 
 # Using AWS ECR as the container registry
 #

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

@@ -58,13 +58,16 @@ ssh:
 
   # Key data
   #
-  # An array of strings, with each element of the array being
-  # a raw private key in PEM format.
-  key_data: [ "-----BEGIN OPENSSH PRIVATE KEY-----" ]
+  # An array of strings, with each element of the array being a secret name.
+  key_data:
+    - SSH_PRIVATE_KEY
+  # You can also provide raw private key in PEM format, but this is deprecated.
+  key_data:
+    - "-----BEGIN OPENSSH PRIVATE KEY----- ..."
 
   # Config
   #
   # Set to true to load the default OpenSSH config files (~/.ssh/config,
   # /etc/ssh_config), to false ignore config files, or to a file path
   # (or array of paths) to load specific configuration. Defaults to true.
-  config: true
+  config: [ "~/.ssh/myconfig" ]

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

@@ -21,3 +21,11 @@ sshkit:
   # 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.
   pool_idle_timeout: 300
+
+  # DNS retry settings
+  #
+  # Some resolvers (mDNSResponder, systemd-resolved, Tailscale) can drop lookups during
+  # bursts of concurrent SSH starts. Kamal will retry DNS failures automatically.
+  #
+  # Number of retries after the initial attempt. Set to 0 to disable.
+  dns_retries: 3

data/lib/kamal/configuration/env.rb

@@ -1,7 +1,7 @@
 class Kamal::Configuration::Env
   include Kamal::Configuration::Validation
 
-  attr_reader :context, :clear, :secret_keys
+  attr_reader :context, :clear, :secrets, :secret_keys
   delegate :argumentize, to: Kamal::Utils
 
   def initialize(config:, secrets:, context: "env")
@@ -23,12 +23,16 @@ class Kamal::Configuration::Env
   def merge(other)
     self.class.new \
       config: { "clear" => clear.merge(other.clear), "secret" => secret_keys | other.secret_keys },
-      secrets: @secrets
+      secrets: secrets
+  end
+
+  def to_h
+    clear.merge(aliased_secrets)
   end
 
   private
     def aliased_secrets
-      secret_keys.to_h { |key| extract_alias(key) }.transform_values { |secret_key| @secrets[secret_key] }
+      secret_keys.to_h { |key| extract_alias(key) }.transform_values { |secret_key| secrets[secret_key] }
     end
 
     def extract_alias(key)

data/lib/kamal/configuration/proxy/boot.rb

@@ -1,9 +1,4 @@
 class Kamal::Configuration::Proxy::Boot
-  MINIMUM_VERSION = "v0.9.0"
-  DEFAULT_HTTP_PORT = 80
-  DEFAULT_HTTPS_PORT = 443
-  DEFAULT_LOG_MAX_SIZE = "10m"
-
   attr_reader :config
   delegate :argumentize, :optionize, to: Kamal::Utils
 
@@ -16,8 +11,8 @@ class Kamal::Configuration::Proxy::Boot
 
     (bind_ips || [ nil ]).map do |bind_ip|
       bind_ip = format_bind_ip(bind_ip)
-      publish_http = [ bind_ip, http_port, DEFAULT_HTTP_PORT ].compact.join(":")
-      publish_https = [ bind_ip, https_port, DEFAULT_HTTPS_PORT ].compact.join(":")
+      publish_http = [ bind_ip, http_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT ].compact.join(":")
+      publish_https = [ bind_ip, https_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT ].compact.join(":")
 
       argumentize "--publish", [ publish_http, publish_https ]
     end.join(" ")
@@ -29,8 +24,8 @@ class Kamal::Configuration::Proxy::Boot
 
   def default_boot_options
     [
-      *(publish_args(DEFAULT_HTTP_PORT, DEFAULT_HTTPS_PORT, nil)),
-      *(logging_args(DEFAULT_LOG_MAX_SIZE))
+      *(publish_args(Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT, nil)),
+      *(logging_args(Kamal::Configuration::Proxy::Run::DEFAULT_LOG_MAX_SIZE))
     ]
   end
 

data/lib/kamal/configuration/proxy/run.rb

@@ -0,0 +1,143 @@
+class Kamal::Configuration::Proxy::Run
+  MINIMUM_VERSION = "v0.9.2"
+  DEFAULT_HTTP_PORT = 80
+  DEFAULT_HTTPS_PORT = 443
+  DEFAULT_LOG_MAX_SIZE = "10m"
+
+  attr_reader :config, :run_config
+  delegate :argumentize, :optionize, to: Kamal::Utils
+
+  def initialize(config, run_config:, context: "proxy/run")
+    @config = config
+    @run_config = run_config
+    @context = context
+  end
+
+  def debug?
+    run_config.fetch("debug", nil)
+  end
+
+  def publish?
+    run_config.fetch("publish", true)
+  end
+
+  def http_port
+    run_config.fetch("http_port", DEFAULT_HTTP_PORT)
+  end
+
+  def https_port
+    run_config.fetch("https_port", DEFAULT_HTTPS_PORT)
+  end
+
+  def bind_ips
+    run_config.fetch("bind_ips", nil)
+  end
+
+  def publish_args
+    if publish?
+      (bind_ips || [ nil ]).map do |bind_ip|
+        bind_ip = format_bind_ip(bind_ip)
+        publish_http = [ bind_ip, http_port, DEFAULT_HTTP_PORT ].compact.join(":")
+        publish_https = [ bind_ip, https_port, DEFAULT_HTTPS_PORT ].compact.join(":")
+
+        argumentize "--publish", [ publish_http, publish_https ]
+      end.join(" ")
+    end
+  end
+
+  def log_max_size
+    run_config.fetch("log_max_size", DEFAULT_LOG_MAX_SIZE)
+  end
+
+  def logging_args
+    argumentize "--log-opt", "max-size=#{log_max_size}" if log_max_size.present?
+  end
+
+  def version
+    run_config.fetch("version", MINIMUM_VERSION)
+  end
+
+  def registry
+    run_config.fetch("registry", nil)
+  end
+
+  def repository
+    run_config.fetch("repository", "basecamp/kamal-proxy")
+  end
+
+  def image
+    "#{[ registry, repository ].compact.join("/")}:#{version}"
+  end
+
+  def container_name
+    "kamal-proxy"
+  end
+
+  def options_args
+    if args = run_config["options"]
+      optionize args
+    end
+  end
+
+  def run_command
+    [ "kamal-proxy", "run", *optionize(run_command_options) ].join(" ")
+  end
+
+  def metrics_port
+    run_config["metrics_port"]
+  end
+
+  def run_command_options
+    { debug: debug? || nil, "metrics-port": metrics_port }.compact
+  end
+
+  def docker_options_args
+    [
+      *apps_volume_args,
+      *publish_args,
+      *logging_args,
+      *("--expose=#{metrics_port}" if metrics_port.present?),
+      *options_args
+    ].compact
+  end
+
+  def host_directory
+    File.join config.run_directory, "proxy"
+  end
+
+  def apps_directory
+    File.join host_directory, "apps-config"
+  end
+
+  def apps_container_directory
+    "/home/kamal-proxy/.apps-config"
+  end
+
+  def apps_volume
+    Kamal::Configuration::Volume.new \
+      host_path: apps_directory,
+      container_path: apps_container_directory
+  end
+
+  def apps_volume_args
+    [ apps_volume.docker_args ]
+  end
+
+  def app_directory
+    File.join apps_directory, config.service_and_destination
+  end
+
+  def app_container_directory
+    File.join apps_container_directory, config.service_and_destination
+  end
+
+  private
+    def format_bind_ip(ip)
+      # Ensure IPv6 address inside square brackets - e.g. [::1]
+      if ip =~ Resolv::IPv6::Regex && ip !~ /\A\[.*\]\z/
+        "[#{ip}]"
+      else
+        ip
+      end
+    end
+end

data/lib/kamal/configuration/proxy.rb

@@ -6,8 +6,7 @@ class Kamal::Configuration::Proxy
 
   delegate :argumentize, :optionize, to: Kamal::Utils
 
-  attr_reader :config, :proxy_config, :role_name, :secrets
-
+  attr_reader :config, :proxy_config, :role_name, :run, :secrets
   def initialize(config:, proxy_config:, role_name: nil, secrets:, context: "proxy")
     @config = config
     @proxy_config = proxy_config
@@ -15,6 +14,7 @@ class Kamal::Configuration::Proxy
     @role_name = role_name
     @secrets = secrets
     validate! @proxy_config, with: Kamal::Configuration::Validator::Proxy, context: context
+    @run = Kamal::Configuration::Proxy::Run.new(config, run_config: @proxy_config["run"], context: "#{context}/run") if @proxy_config && @proxy_config["run"].present?
   end
 
   def app_port
@@ -63,6 +63,10 @@ class Kamal::Configuration::Proxy
     tls_path(config.proxy_boot.tls_container_directory, "key.pem") if custom_ssl_certificate?
   end
 
+  def path_prefixes
+    proxy_config["path_prefixes"] || proxy_config["path_prefix"]&.split(",") || []
+  end
+
   def deploy_options
     {
       host: hosts,
@@ -80,7 +84,7 @@ class Kamal::Configuration::Proxy
       "buffer-memory": proxy_config.dig("buffering", "memory"),
       "max-request-body": proxy_config.dig("buffering", "max_request_body"),
       "max-response-body": proxy_config.dig("buffering", "max_response_body"),
-      "path-prefix": proxy_config.dig("path_prefix"),
+      "path-prefix": path_prefixes,
       "strip-path-prefix": proxy_config.dig("strip_path_prefix"),
       "forward-headers": proxy_config.dig("forward_headers"),
       "tls-redirect": proxy_config.dig("ssl_redirect"),

data/lib/kamal/configuration/registry.rb

@@ -19,6 +19,14 @@ class Kamal::Configuration::Registry
     lookup("password")
   end
 
+  def local?
+    server.to_s.match?("^localhost[:$]")
+  end
+
+  def local_port
+    local? ? (server.split(":").last.to_i || 80) : nil
+  end
+
   private
     attr_reader :registry_config, :secrets
 

data/lib/kamal/configuration/role.rb

@@ -36,7 +36,7 @@ class Kamal::Configuration::Role
   end
 
   def env_tags(host)
-    tagged_hosts.fetch(host).collect { |tag| config.env_tag(tag) }
+    tagged_hosts.fetch(host).collect { |tag| config.env_tag(tag) }.compact
   end
 
   def cmd
@@ -127,7 +127,7 @@ class Kamal::Configuration::Role
 
 
   def asset_path
-    specializations["asset_path"] || config.asset_path
+    asset_path_config&.dig(0)
   end
 
   def assets?
@@ -137,10 +137,14 @@ class Kamal::Configuration::Role
   def asset_volume(version = config.version)
     if assets?
       Kamal::Configuration::Volume.new \
-        host_path: asset_volume_directory(version), container_path: asset_path
+        host_path: asset_volume_directory(version), container_path: asset_path, options: asset_path_options
     end
   end
 
+  def asset_path_options
+    asset_path_config&.dig(1)
+  end
+
   def asset_extracted_directory(version = config.version)
     File.join config.assets_directory, "extracted", [ name, version ].join("-")
   end
@@ -219,4 +223,12 @@ class Kamal::Configuration::Role
         labels.merge!(specializations["labels"]) if specializations["labels"].present?
       end
     end
+
+    def asset_path_config
+      raw_path = specializations["asset_path"] || config.asset_path
+      return nil unless raw_path.present?
+
+      parts = raw_path.split(":", 2)
+      [ parts[0], parts[1] ]
+    end
 end

data/lib/kamal/configuration/ssh.rb

@@ -3,10 +3,11 @@ class Kamal::Configuration::Ssh
 
   include Kamal::Configuration::Validation
 
-  attr_reader :ssh_config
+  attr_reader :ssh_config, :secrets
 
   def initialize(config:)
     @ssh_config = config.raw_config.ssh || {}
+    @secrets = config.secrets
     validate! ssh_config
   end
 
@@ -35,11 +36,25 @@ class Kamal::Configuration::Ssh
   end
 
   def key_data
-    ssh_config["key_data"]
+    key_data = ssh_config["key_data"]
+    return unless key_data
+
+    key_data.map do |k|
+      if secrets.key?(k)
+        secrets[k]
+      else
+        warn "Inline key_data usage is deprecated and will be removed in Kamal 3. Please store your key_data in a secret."
+        k
+      end
+    end
+  end
+
+  def config
+    ssh_config["config"]
   end
 
   def options
-    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data }.compact
+    { user: user, port: port, proxy: proxy, logger: logger, keepalive: true, keepalive_interval: 30, keys_only: keys_only, keys: keys, key_data: key_data, config: config  }.compact
   end
 
   def to_h

data/lib/kamal/configuration/sshkit.rb

@@ -16,6 +16,10 @@ class Kamal::Configuration::Sshkit
     sshkit_config.fetch("pool_idle_timeout", 900)
   end
 
+  def dns_retries
+    Integer(sshkit_config.fetch("dns_retries", 3))
+  end
+
   def to_h
     sshkit_config
   end

data/lib/kamal/configuration/validator/proxy.rb

@@ -20,6 +20,26 @@ class Kamal::Configuration::Validator::Proxy < Kamal::Configuration::Validator
           error "Missing certificate_pem setting (required when private_key_pem is present)"
         end
       end
+
+      if run_config = config["run"]
+        if run_config["bind_ips"].present?
+          ensure_valid_bind_ips(config["bind_ips"])
+        end
+
+        if run_config["publish"] == false
+          if run_config["bind_ips"].present? || run_config["http_port"].present? || run_config["https_port"].present?
+            error "Cannot set http_port, https_port or bind_ips when publish is false"
+          end
+        end
+      end
     end
   end
+
+  private
+    def ensure_valid_bind_ips(bind_ips)
+      bind_ips.present? && bind_ips.each do |ip|
+        next if ip =~ Resolv::IPv4::Regex || ip =~ Resolv::IPv6::Regex
+        error "Invalid publish IP address: #{ip}"
+      end
+    end
 end

data/lib/kamal/configuration/validator/registry.rb

@@ -15,10 +15,12 @@ class Kamal::Configuration::Validator::Registry < Kamal::Configuration::Validato
       with_context(key) do
         value = config[key]
 
-        error "is required" unless value.present?
+        unless config["server"]&.match?("^localhost[:$]")
+          error "is required" unless value.present?
 
-        unless value.is_a?(String) || (value.is_a?(Array) && value.size == 1 && value.first.is_a?(String))
-          error "should be a string or an array with one string (for secret lookup)"
+          unless value.is_a?(String) || (value.is_a?(Array) && value.size == 1 && value.first.is_a?(String))
+            error "should be a string or an array with one string (for secret lookup)"
+          end
         end
       end
     end