kamal 2.10.1 → 2.12.0

data/lib/kamal/commands/base.rb

@@ -11,11 +11,11 @@ module Kamal::Commands
     end
 
     def run_over_ssh(*command, host:)
-      "ssh#{ssh_proxy_args}#{ssh_keys_args} -t #{config.ssh.user}@#{host} -p #{config.ssh.port} '#{command.join(" ").gsub("'", "'\\\\''")}'"
+      "ssh#{ssh_config_args}#{ssh_proxy_args}#{ssh_keys_args} -t #{config.ssh.user}@#{host} -p #{config.ssh.port} '#{command.join(" ").gsub("'", "'\\\\''")}'"
     end
 
     def container_id_for(container_name:, only_running: false)
-      docker :container, :ls, *("--all" unless only_running), "--filter", "name=^#{container_name}$", "--quiet"
+      docker :container, :ls, *("--all" unless only_running), "--filter", "'name=^#{container_name}$'", "--quiet"
     end
 
     def make_directory_for(remote_file)
@@ -100,6 +100,19 @@ module Kamal::Commands
         Kamal::Tags.from_config(config, **details)
       end
 
+      def ssh_config_args
+        case config.ssh.config
+        when Array
+          config.ssh.config.map { |file| " -F #{file}" }.join
+        when String
+          " -F #{config.ssh.config}"
+        when true
+          "" # Use default SSH config
+        when false
+          " -F /dev/null" # Ignore SSH config
+        end
+      end
+
       def ssh_proxy_args
         case config.ssh.proxy
         when Net::SSH::Proxy::Jump

data/lib/kamal/commands/builder/clone.rb

@@ -9,7 +9,8 @@ module Kamal::Commands::Builder::Clone
       git(:fetch, :origin, path: escaped_build_directory),
       git(:reset, "--hard", Kamal::Git.revision, path: escaped_build_directory),
       git(:clean, "-fdx", path: escaped_build_directory),
-      git(:submodule, :update, "--init", path: escaped_build_directory)
+      git(:submodule, :update, "--init", path: escaped_build_directory),
+      git(:gc, "--auto", "--quiet", path: escaped_build_directory)
     ]
   end
 

data/lib/kamal/commands/docker.rb

@@ -16,7 +16,23 @@ class Kamal::Commands::Docker < Kamal::Commands::Base
 
   # Do we have superuser access to install Docker and start system services?
   def superuser?
-    [ '[ "${EUID:-$(id -u)}" -eq 0 ] || command -v sudo >/dev/null || command -v su >/dev/null' ]
+    [ '[ "${EUID:-$(id -u)}" -eq 0 ] || sudo -nl usermod >/dev/null' ]
+  end
+
+  def root?
+    [ '[ "${EUID:-$(id -u)}" -eq 0 ]' ]
+  end
+
+  def in_docker_group?
+    [ 'id -nG "${USER:-$(id -un)}" | grep -qw docker' ]
+  end
+
+  def add_to_docker_group
+    [ 'sudo -n usermod -aG docker "${USER:-$(id -un)}"' ]
+  end
+
+  def refresh_session
+    [ "kill -HUP $PPID" ]
   end
 
   def create_network

data/lib/kamal/commands/proxy.rb

@@ -37,7 +37,7 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
   end
 
   def info
-    docker :ps, "--filter", "name=^#{container_name}$"
+    docker :ps, "--filter", "'name=^#{container_name}$'"
   end
 
   def version

data/lib/kamal/configuration/accessory.rb

@@ -102,11 +102,11 @@ class Kamal::Configuration::Accessory
   end
 
   def option_args
-    if args = accessory_config["options"]
-      optionize args
-    else
-      []
-    end
+    optionize docker_options.reject { |key, _| key.to_s == "restart" }
+  end
+
+  def restart_policy
+    restart_policy_option || "unless-stopped"
   end
 
   def cmd
@@ -173,6 +173,14 @@ class Kamal::Configuration::Accessory
       accessory_config["volumes"] || []
     end
 
+    def docker_options
+      accessory_config["options"] || {}
+    end
+
+    def restart_policy_option
+      docker_options.find { |key, _| key.to_s == "restart" }&.last
+    end
+
     def path_volumes(paths)
       paths.map do |local, config|
         Kamal::Configuration::Volume.new \

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

@@ -24,3 +24,6 @@ aliases:
 # Each alias is named and can only contain lowercase letters, numbers, dashes, and underscores:
 aliases:
   uname: app exec -p -q -r web "uname -a"
+#
+# Aliases can include a destination with the `-d` flag:
+  staging_deploy: deploy -d staging

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

@@ -85,16 +85,38 @@ 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):
+# 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.
-# Any files in the format 4xx.html or 5xx.html will be copied to the hosts.
+# 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
@@ -139,6 +161,13 @@ deploy_timeout: 10
 # 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`:
@@ -186,6 +215,12 @@ boot:
 logging:
   ...
 
+# Output
+#
+# Configure output loggers (OTel, file), see kamal docs output:
+output:
+  ...
+
 # Aliases
 #
 # Alias configuration, see kamal docs alias:

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

@@ -14,12 +14,14 @@ env:
 
 # Secrets
 #
-# Kamal uses dotenv to automatically load environment variables set in the `.kamal/secrets` file.
+# Kamal uses dotenv to automatically load environment variables from the configured secrets files.
 #
-# 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`. Kamal looks for
+# `.kamal/secrets-common` first, then `.kamal/secrets`, with later values overriding earlier ones.
 #
-# Common secrets across all destinations can be set in `.kamal/secrets-common`.
+# 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.

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/role.yml

@@ -39,6 +39,7 @@ servers:
       - 172.1.0.3
       - 172.1.0.4: experiment1
     cmd: "bin/jobs"
+    stop_timeout: 30
     options:
       memory: 2g
       cpus: 4

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

@@ -71,3 +71,11 @@ ssh:
   # /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: [ "~/.ssh/myconfig" ]
+
+  # Forward agent
+  #
+  # Whether to forward the local SSH agent to the remote host. Defaults to
+  # true (sshkit's default). Set to false when connecting through a jump
+  # host or tunnel that does not support agent forwarding (for example,
+  # Cloudflare Access for Infrastructure with SSH).
+  forward_agent: false

data/lib/kamal/configuration/output.rb

@@ -0,0 +1,34 @@
+class Kamal::Configuration::Output
+  include Kamal::Configuration::Validation
+
+  LOGGER_TYPES = {
+    "otel" => "Kamal::Output::OtelLogger",
+    "file" => "Kamal::Output::FileLogger"
+  }
+
+  attr_reader :output_config, :loggers
+
+  def initialize(config:)
+    @config = config
+    @output_config = config.raw_config.output || {}
+    validate! @output_config unless @output_config.empty?
+    @loggers = build_loggers
+  end
+
+  def enabled?
+    output_config.present?
+  end
+
+  def to_h
+    output_config
+  end
+
+  private
+    def build_loggers
+      output_config.filter_map do |key, settings|
+        if (klass_name = LOGGER_TYPES[key])
+          klass_name.constantize.build(settings: settings || {}, config: @config)
+        end
+      end
+    end
+end

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

@@ -1,5 +1,5 @@
 class Kamal::Configuration::Proxy::Run
-  MINIMUM_VERSION = "v0.9.0"
+  MINIMUM_VERSION = "v0.9.2"
   DEFAULT_HTTP_PORT = 80
   DEFAULT_HTTPS_PORT = 443
   DEFAULT_LOG_MAX_SIZE = "10m"
@@ -131,6 +131,15 @@ class Kamal::Configuration::Proxy::Run
     File.join apps_container_directory, config.service_and_destination
   end
 
+  def ==(other)
+    other.is_a?(self.class) && run_config == other.run_config
+  end
+  alias_method :eql?, :==
+
+  def hash
+    run_config.hash
+  end
+
   private
     def format_bind_ip(ip)
       # Ensure IPv6 address inside square brackets - e.g. [::1]

data/lib/kamal/configuration/role.rb

@@ -44,11 +44,11 @@ class Kamal::Configuration::Role
   end
 
   def option_args
-    if args = specializations["options"]
-      optionize args
-    else
-      []
-    end
+    optionize docker_options.reject { |key, _| key.to_s == "restart" }
+  end
+
+  def restart_policy
+    restart_policy_option || "unless-stopped"
   end
 
   def labels
@@ -81,11 +81,15 @@ class Kamal::Configuration::Role
 
   def stop_args
     # When deploying with the proxy, kamal-proxy will drain request before returning so we don't need to wait.
-    timeout = running_proxy? ? nil : config.drain_timeout
+    timeout = stop_timeout || (running_proxy? ? nil : config.drain_timeout)
 
     [ *argumentize("-t", timeout) ]
   end
 
+  def stop_timeout
+    specializations["stop_timeout"] || config.stop_timeout
+  end
+
   def env(host)
     @envs ||= {}
     @envs[host] ||= [ config.env, specialized_env, *env_tags(host).map(&:env) ].reduce(:merge)
@@ -217,6 +221,14 @@ class Kamal::Configuration::Role
       @role_config ||= config.raw_config.servers.is_a?(Array) ? {} : config.raw_config.servers[name]
     end
 
+    def docker_options
+      specializations["options"] || {}
+    end
+
+    def restart_policy_option
+      docker_options.find { |key, _| key.to_s == "restart" }&.last
+    end
+
     def custom_labels
       Hash.new.tap do |labels|
         labels.merge!(config.labels) if config.labels.present?

data/lib/kamal/configuration/ssh.rb

@@ -53,8 +53,12 @@ class Kamal::Configuration::Ssh
     ssh_config["config"]
   end
 
+  def forward_agent
+    ssh_config["forward_agent"]
+  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, config: config  }.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, forward_agent: forward_agent }.compact
   end
 
   def to_h

data/lib/kamal/configuration/validator.rb

@@ -29,6 +29,8 @@ class Kamal::Configuration::Validator
               end
             elsif key.to_s == "ssl"
                 validate_type! value, TrueClass, FalseClass, Hash
+            elsif key.to_s == "hooks_output"
+                validate_hooks_output!(value)
             elsif key == "hosts"
               validate_servers! value
             elsif example_value.is_a?(Array)
@@ -161,6 +163,19 @@ class Kamal::Configuration::Validator
       end
     end
 
+    def validate_hooks_output!(value)
+      # hooks_output can be either a symbol/string (global) or a hash (per-hook)
+      if value.is_a?(Hash)
+        value.each do |hook, level|
+          with_context(hook) do
+            validate_type! level, String, Symbol
+          end
+        end
+      else
+        validate_type! value, String, Symbol
+      end
+    end
+
     def validate_type!(value, *types)
       type_error(*types) unless types.any? { |type| valid_type?(value, type) }
     end
@@ -217,8 +232,20 @@ class Kamal::Configuration::Validator
     end
 
     def validate_docker_options!(options)
-      if options
-        error "Cannot set restart policy in docker options, unless-stopped is required" if options["restart"]
+      if restart_policy = options&.find { |key, _| key.to_s == "restart" }
+        validate_restart_policy!(restart_policy.last)
+      end
+    end
+
+    def validate_restart_policy!(restart_policy)
+      with_context("options/restart") do
+        unless restart_policy.is_a?(String)
+          error %(should be a string. Use "no" to disable restarts)
+        end
+
+        unless restart_policy.match?(/\A(?:no|always|unless-stopped|on-failure(?::\d+)?)\z/)
+          error "should be no, always, unless-stopped, on-failure, or on-failure:N"
+        end
       end
     end
 end

data/lib/kamal/configuration.rb

@@ -6,11 +6,13 @@ require "erb"
 require "net/ssh/proxy/jump"
 
 class Kamal::Configuration
+  HOOKS_OUTPUT_LEVELS = [ :quiet, :verbose ].freeze
+
   delegate :service, :labels, :hooks_path, to: :raw_config, allow_nil: true
   delegate :argumentize, :optionize, to: Kamal::Utils
 
   attr_reader :destination, :raw_config, :secrets
-  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :proxy, :proxy_boot, :servers, :ssh, :sshkit, :registry
+  attr_reader :accessories, :aliases, :boot, :builder, :env, :logging, :output, :proxy, :proxy_boot, :servers, :ssh, :sshkit, :registry
 
   include Validation
 
@@ -18,11 +20,15 @@ class Kamal::Configuration
     def create_from(config_file:, destination: nil, version: nil)
       ENV["KAMAL_DESTINATION"] = destination
 
-      raw_config = load_config_files(config_file, *destination_config_file(config_file, destination))
+      raw_config = load_raw_config(config_file: config_file, destination: destination)
 
       new raw_config, destination: destination, version: version
     end
 
+    def load_raw_config(config_file:, destination: nil)
+      load_config_files(config_file, *destination_config_file(config_file, destination))
+    end
+
     private
       def load_config_files(*files)
         files.inject({}) { |config, file| config.deep_merge! load_config_file(file) }
@@ -32,7 +38,9 @@ class Kamal::Configuration
         if file.exist?
           # Newer Psych doesn't load aliases by default
           load_method = YAML.respond_to?(:unsafe_load) ? :unsafe_load : :load
-          YAML.send(load_method, ERB.new(File.read(file)).result).symbolize_keys
+          template = File.read(file)
+          rendered = ERB.new(template, trim_mode: "-").result
+          YAML.send(load_method, rendered).symbolize_keys
         else
           raise "Configuration file not found in #{file}"
         end
@@ -63,6 +71,7 @@ class Kamal::Configuration
     @env = Env.new(config: @raw_config.env || {}, secrets: secrets)
 
     @logging = Logging.new(logging_config: @raw_config.logging)
+    @output = Output.new(config: self)
     @proxy = Proxy.new(config: self, proxy_config: @raw_config.proxy, secrets: secrets)
     @proxy_boot = Proxy::Boot.new(config: self)
     @ssh = Ssh.new(config: self)
@@ -78,6 +87,7 @@ class Kamal::Configuration
     ensure_unique_hosts_for_ssl_roles
     ensure_local_registry_remote_builder_has_ssh_url
     ensure_no_conflicting_proxy_runs
+    ensure_valid_hooks_output!
   end
 
   def version=(version)
@@ -231,6 +241,10 @@ class Kamal::Configuration
     raw_config.drain_timeout || 30
   end
 
+  def stop_timeout
+    raw_config.stop_timeout
+  end
+
   def run_directory
     ".kamal"
   end
@@ -279,6 +293,15 @@ class Kamal::Configuration
     env_tags.detect { |t| t.name == name.to_s }
   end
 
+  def hooks_output_for(hook)
+    case raw_config.hooks_output
+    when Symbol, String
+      raw_config.hooks_output.to_sym
+    when Hash
+      raw_config.hooks_output[hook]&.to_sym
+    end
+  end
+
   def to_h
     {
       roles: role_names,
@@ -409,6 +432,21 @@ class Kamal::Configuration
       raw_config.servers.is_a?(Array) ? [ "web" ] : raw_config.servers.keys.sort
     end
 
+    def ensure_valid_hooks_output!
+      case raw_config.hooks_output
+      when Symbol, String
+        validate_hooks_output_level!(raw_config.hooks_output.to_sym)
+      when Hash
+        raw_config.hooks_output.each { |hook, level| validate_hooks_output_level!(level.to_sym, hook) }
+      end
+    end
+
+    def validate_hooks_output_level!(level, hook = nil)
+      return if HOOKS_OUTPUT_LEVELS.include?(level)
+      context = hook ? " for hook '#{hook}'" : ""
+      raise Kamal::ConfigurationError, "Invalid hooks_output '#{level}'#{context}, must be one of: #{HOOKS_OUTPUT_LEVELS.join(', ')}"
+    end
+
     def git_version
       @git_version ||=
         if Kamal::Git.used?

data/lib/kamal/git.rb

@@ -6,7 +6,7 @@ module Kamal::Git
   end
 
   def user_name
-    `git config user.name`.strip
+    `git config user.name`.force_encoding(Encoding::UTF_8).strip
   end
 
   def email