kamal 2.7.0 → 2.11.0

data/lib/kamal/commands/accessory.rb

@@ -68,6 +68,7 @@ class Kamal::Commands::Accessory < Kamal::Commands::Base
       *network_args,
       *env_args,
       *volume_args,
+      *option_args,
       image,
       *command
   end
@@ -90,6 +91,10 @@ class Kamal::Commands::Accessory < Kamal::Commands::Base
     end
   end
 
+  def pull_image
+    docker :image, :pull, image
+  end
+
   def remove_service_directory
     [ :rm, "-rf", service_name ]
   end

data/lib/kamal/commands/app/execution.rb

@@ -12,6 +12,7 @@ module Kamal::Commands::App::Execution
       (docker_interactive_args if interactive),
       ("--detach" if detach),
       ("--rm" unless detach),
+      "--name", container_name_for_exec,
       "--network", "kamal",
       *role&.env_args(host),
       *argumentize("--env", env),
@@ -22,11 +23,16 @@ module Kamal::Commands::App::Execution
       *command
   end
 
-  def execute_in_existing_container_over_ssh(*command,  env:)
+  def execute_in_existing_container_over_ssh(*command, env:)
     run_over_ssh execute_in_existing_container(*command, interactive: true, env: env), host: host
   end
 
   def execute_in_new_container_over_ssh(*command, env:)
     run_over_ssh execute_in_new_container(*command, interactive: true, env: env), host: host
   end
+
+  private
+    def container_name_for_exec
+      [ role.container_prefix, "exec", config.version, SecureRandom.hex(3) ].compact.join("-")
+    end
 end

data/lib/kamal/commands/app.rb

@@ -23,6 +23,7 @@ class Kamal::Commands::App < Kamal::Commands::Base
       "--env", "KAMAL_CONTAINER_NAME=\"#{container_name}\"",
       "--env", "KAMAL_VERSION=\"#{config.version}\"",
       "--env", "KAMAL_HOST=\"#{host}\"",
+      *([ "--env", "KAMAL_DESTINATION=\"#{config.destination}\"" ] if config.destination),
       *role.env_args(host),
       *role.logging_args,
       *config.volume_args,

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/base.rb

@@ -14,13 +14,14 @@ class Kamal::Commands::Builder::Base < Kamal::Commands::Base
     docker :image, :rm, "--force", config.absolute_image
   end
 
-  def push(export_action = "registry", tag_as_dirty: false)
+  def push(export_action = "registry", tag_as_dirty: false, no_cache: false)
     docker :buildx, :build,
       "--output=type=#{export_action}",
       *platform_options(arches),
       *([ "--builder", builder_name ] unless docker_driver?),
       *build_tag_options(tag_as_dirty: tag_as_dirty),
       *build_options,
+      *([ "--no-cache" ] if no_cache),
       build_context,
       "2>&1"
   end
@@ -60,6 +61,14 @@ class Kamal::Commands::Builder::Base < Kamal::Commands::Base
     docker(:info, "--format '{{index .RegistryConfig.Mirrors 0}}'")
   end
 
+  def login_to_registry_locally?
+    true
+  end
+
+  def push_env
+    {}
+  end
+
   private
     def build_tag_names(tag_as_dirty: false)
       tag_names = [ config.absolute_image, config.latest_image ]
@@ -118,6 +127,16 @@ class Kamal::Commands::Builder::Base < Kamal::Commands::Base
       config.builder
     end
 
+    def registry_config
+      config.registry
+    end
+
+    def driver_options
+      if registry_config.local?
+        [ "--driver-opt", "network=host" ]
+      end
+    end
+
     def platform_options(arches)
       argumentize "--platform", arches.map { |arch| "linux/#{arch}" }.join(",") if arches.any?
     end

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

@@ -8,14 +8,14 @@ class Kamal::Commands::Builder::Hybrid < Kamal::Commands::Builder::Remote
 
   private
     def builder_name
-      "kamal-hybrid-#{driver}-#{remote.gsub(/[^a-z0-9_-]/, "-")}"
+      "kamal-hybrid-#{driver}-#{remote_builder_name_suffix}"
     end
 
     def create_local_buildx
-      docker :buildx, :create, *platform_options(local_arches), "--name", builder_name, "--driver=#{driver}"
+      docker :buildx, :create, *platform_options(local_arches), "--name", builder_name, "--driver=#{driver}", *driver_options
     end
 
     def append_remote_buildx
-      docker :buildx, :create, *platform_options(remote_arches), "--append", "--name", builder_name, remote_context_name
+      docker :buildx, :create, *platform_options(remote_arches), "--append", "--name", builder_name, *driver_options, remote_context_name
     end
 end

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

@@ -1,6 +1,8 @@
 class Kamal::Commands::Builder::Local < Kamal::Commands::Builder::Base
   def create
-    docker :buildx, :create, "--name", builder_name, "--driver=#{driver}" unless docker_driver?
+    return if docker_driver?
+
+    docker :buildx, :create, "--name", builder_name, "--driver=#{driver}", *driver_options
   end
 
   def remove
@@ -9,6 +11,10 @@ class Kamal::Commands::Builder::Local < Kamal::Commands::Builder::Base
 
   private
     def builder_name
-      "kamal-local-#{driver}"
+      if registry_config.local?
+        "kamal-local-registry-#{driver}"
+      else
+        "kamal-local-#{driver}"
+      end
     end
 end

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

@@ -1,7 +1,7 @@
 class Kamal::Commands::Builder::Pack < Kamal::Commands::Builder::Base
-  def push(export_action = "registry")
+  def push(export_action = "registry", tag_as_dirty: false, no_cache: false)
     combine \
-      build,
+      build(tag_as_dirty: tag_as_dirty, no_cache: no_cache),
       export(export_action)
   end
 
@@ -13,15 +13,15 @@ class Kamal::Commands::Builder::Pack < Kamal::Commands::Builder::Base
   alias_method :inspect_builder, :info
 
   private
-    def build
+    def build(tag_as_dirty: false, no_cache: false)
       pack(:build,
         config.repository,
         "--platform", platform,
         "--creation-time", "now",
         "--builder", pack_builder,
         buildpacks,
-        "-t", config.absolute_image,
-        "-t", config.latest_image,
+        *build_tag_options(tag_as_dirty: tag_as_dirty),
+        *([ "--clear-cache" ] if no_cache),
         "--env", "BP_IMAGE_LABELS=service=#{config.service}",
         *argumentize("--env", args),
         *argumentize("--env", secrets, sensitive: true),

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

@@ -19,20 +19,32 @@ class Kamal::Commands::Builder::Remote < Kamal::Commands::Builder::Base
 
   def inspect_builder
     combine \
-      combine inspect_buildx, inspect_remote_context,
+      combine(inspect_buildx, inspect_remote_context),
       [ "(echo no compatible builder && exit 1)" ],
       by: "||"
   end
 
+  def login_to_registry_locally?
+    false
+  end
+
+  def push_env
+    { "BUILDKIT_NO_CLIENT_TOKEN" => "1" }
+  end
+
   private
     def builder_name
-      "kamal-remote-#{remote.gsub(/[^a-z0-9_-]/, "-")}"
+      "kamal-remote-#{remote_builder_name_suffix}"
     end
 
     def remote_context_name
       "#{builder_name}-context"
     end
 
+    def remote_builder_name_suffix
+      "#{remote.gsub(/[^a-z0-9_-]/, "-")}#{registry_config.local? ? "-local-registry" : "" }"
+    end
+
     def inspect_buildx
       pipe \
         docker(:buildx, :inspect, builder_name),
@@ -54,7 +66,7 @@ class Kamal::Commands::Builder::Remote < Kamal::Commands::Builder::Base
     end
 
     def create_buildx
-      docker :buildx, :create, "--name", builder_name, remote_context_name
+      docker :buildx, :create, "--name", builder_name, *driver_options, remote_context_name
     end
 
     def remove_buildx

data/lib/kamal/commands/builder.rb

@@ -1,8 +1,14 @@
 require "active_support/core_ext/string/filters"
 
 class Kamal::Commands::Builder < Kamal::Commands::Base
-  delegate :create, :remove, :dev, :push, :clean, :pull, :info, :inspect_builder, :validate_image, :first_mirror, to: :target
-  delegate :local?, :remote?, :pack?, :cloud?, to: "config.builder"
+  delegate \
+    :create, :remove, :dev, :push, :clean, :pull, :info, :inspect_builder,
+    :validate_image, :first_mirror, :login_to_registry_locally?, :push_env,
+    to: :target
+
+  delegate \
+    :local?, :remote?, :pack?, :cloud?,
+    to: "config.builder"
 
   include Clone
 

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

@@ -1,8 +1,27 @@
 class Kamal::Commands::Proxy < Kamal::Commands::Base
   delegate :argumentize, :optionize, to: Kamal::Utils
+  attr_reader :proxy_run_config
+
+  def initialize(config, host:)
+    super(config)
+    @proxy_run_config = config.proxy_run(host)
+  end
 
   def run
-    pipe boot_config, xargs(docker_run)
+    if proxy_run_config
+      docker \
+        :run,
+        "--name", container_name,
+        "--network", "kamal",
+        "--detach",
+        "--restart", "unless-stopped",
+        "--volume", "kamal-proxy-config:/home/kamal-proxy/.config/kamal-proxy",
+        *proxy_run_config.docker_options_args,
+        *proxy_run_config.image,
+        *proxy_run_config.run_command
+    else
+      pipe boot_config, xargs(docker_run)
+    end
   end
 
   def start
@@ -18,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
@@ -82,7 +101,7 @@ class Kamal::Commands::Proxy < Kamal::Commands::Base
   end
 
   def read_image_version
-    read_file(config.proxy_boot.image_version_file, default: Kamal::Configuration::Proxy::Boot::MINIMUM_VERSION)
+    read_file(config.proxy_boot.image_version_file, default: Kamal::Configuration::Proxy::Run::MINIMUM_VERSION)
   end
 
   def read_run_command

data/lib/kamal/commands/registry.rb

@@ -2,6 +2,8 @@ class Kamal::Commands::Registry < Kamal::Commands::Base
   def login(registry_config: nil)
     registry_config ||= config.registry
 
+    return if registry_config.local?
+
     docker :login,
       registry_config.server,
       "-u", sensitive(Kamal::Utils.escape_shell_value(registry_config.username)),
@@ -13,4 +15,24 @@ class Kamal::Commands::Registry < Kamal::Commands::Base
 
     docker :logout, registry_config.server
   end
+
+  def setup(registry_config: nil)
+    registry_config ||= config.registry
+
+    combine \
+      docker(:start, "kamal-docker-registry"),
+      docker(:run, "--detach", "-p", "127.0.0.1:#{registry_config.local_port}:5000", "--name", "kamal-docker-registry", "registry:3"),
+      by: "||"
+  end
+
+  def remove
+    combine \
+      docker(:stop, "kamal-docker-registry"),
+      docker(:rm, "kamal-docker-registry"),
+      by: "&&"
+  end
+
+  def local?
+    config.registry.local?
+  end
 end

data/lib/kamal/configuration/accessory.rb

@@ -74,25 +74,31 @@ class Kamal::Configuration::Accessory
   end
 
   def files
-    accessory_config["files"]&.to_h do |local_to_remote_mapping|
-      local_file, remote_file = local_to_remote_mapping.split(":")
-      [ expand_local_file(local_file), expand_remote_file(remote_file) ]
+    accessory_config["files"]&.to_h do |config|
+      parse_path_config(config, default_mode: "755") do |local, remote|
+        {
+          key: expand_local_file(local),
+          host_path: expand_remote_file(remote),
+          container_path: remote
+        }
+      end
     end || {}
   end
 
   def directories
-    accessory_config["directories"]&.to_h do |host_to_container_mapping|
-      host_path, container_path = host_to_container_mapping.split(":")
-      [ expand_host_path(host_path), container_path ]
+    accessory_config["directories"]&.to_h do |config|
+      parse_path_config(config, default_mode: nil) do |local, remote|
+        {
+          key: expand_host_path(local),
+          host_path: expand_host_path_for_volume(local),
+          container_path: remote
+        }
+      end
     end || {}
   end
 
-  def volumes
-    specific_volumes + remote_files_as_volumes + remote_directories_as_volumes
-  end
-
   def volume_args
-    argumentize "--volume", volumes
+    argumentize("--volume", specific_volumes) + (path_volumes(files) + path_volumes(directories)).flat_map(&:docker_args)
   end
 
   def option_args
@@ -142,17 +148,17 @@ class Kamal::Configuration::Accessory
 
     def expand_local_file(local_file)
       if local_file.end_with?("erb")
-        with_clear_env_loaded { read_dynamic_file(local_file) }
+        with_env_loaded { read_dynamic_file(local_file) }
       else
         Pathname.new(File.expand_path(local_file)).to_s
       end
     end
 
-    def with_clear_env_loaded
-      env.clear.each { |k, v| ENV[k] = v }
+    def with_env_loaded
+      env.to_h.each { |k, v| ENV[k] = v }
       yield
     ensure
-      env.clear.each { |k, v| ENV.delete(k) }
+      env.to_h.each { |k, v| ENV.delete(k) }
     end
 
     def read_dynamic_file(local_file)
@@ -167,24 +173,49 @@ class Kamal::Configuration::Accessory
       accessory_config["volumes"] || []
     end
 
-    def remote_files_as_volumes
-      accessory_config["files"]&.collect do |local_to_remote_mapping|
-        _, remote_file = local_to_remote_mapping.split(":")
-        "#{service_data_directory + remote_file}:#{remote_file}"
-      end || []
+    def path_volumes(paths)
+      paths.map do |local, config|
+        Kamal::Configuration::Volume.new \
+          host_path: config[:host_path],
+          container_path: config[:container_path],
+          options: config[:options]
+      end
     end
 
-    def remote_directories_as_volumes
-      accessory_config["directories"]&.collect do |host_to_container_mapping|
-        host_path, container_path = host_to_container_mapping.split(":")
-        [ expand_host_path(host_path), container_path ].join(":")
-      end || []
+    def parse_path_config(config, default_mode:)
+      if config.is_a?(Hash)
+        local, remote = config["local"], config["remote"]
+        expanded = yield(local, remote)
+        [
+          expanded[:key],
+          expanded.except(:key).merge(
+            options: config["options"],
+            mode: config["mode"] || default_mode,
+            owner: config["owner"]
+          )
+        ]
+      else
+        local, remote, options = config.split(":", 3)
+        expanded = yield(local, remote)
+        [
+          expanded[:key],
+          expanded.except(:key).merge(
+            options: options,
+            mode: default_mode,
+            owner: nil
+          )
+        ]
+      end
     end
 
     def expand_host_path(host_path)
       absolute_path?(host_path) ? host_path : File.join(service_data_directory, host_path)
     end
 
+    def expand_host_path_for_volume(host_path)
+      absolute_path?(host_path) ? host_path : File.join(service_name, host_path)
+    end
+
     def absolute_path?(path)
       Pathname.new(path).absolute?
     end

data/lib/kamal/configuration/boot.rb

@@ -22,4 +22,8 @@ class Kamal::Configuration::Boot
   def wait
     boot_config["wait"]
   end
+
+  def parallel_roles
+    boot_config["parallel_roles"]
+  end
 end

data/lib/kamal/configuration/builder.rb

@@ -177,8 +177,15 @@ class Kamal::Configuration::Builder
       [ server, cache_image ].compact.join("/")
     end
 
+    def cache_options
+      builder_config["cache"]&.fetch("options", nil)
+    end
+
     def cache_from_config_for_gha
-      "type=gha"
+      individual_options = cache_options&.split(",") || []
+      allowed_options = individual_options.select { |option| option =~ /^(url|url_v2|token|scope|timeout)=/ }
+
+      [ "type=gha", *allowed_options ].compact.join(",")
     end
 
     def cache_from_config_for_registry
@@ -186,11 +193,11 @@ class Kamal::Configuration::Builder
     end
 
     def cache_to_config_for_gha
-      [ "type=gha", builder_config["cache"]&.fetch("options", nil) ].compact.join(",")
+      [ "type=gha", cache_options ].compact.join(",")
     end
 
     def cache_to_config_for_registry
-      [ "type=registry", "ref=#{cache_image_ref}", builder_config["cache"]&.fetch("options", nil) ].compact.join(",")
+      [ "type=registry", "ref=#{cache_image_ref}", cache_options ].compact.join(",")
     end
 
     def repo_basename

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

@@ -90,22 +90,54 @@ accessories:
     # Copying files
     #
     # You can specify files to mount into the container.
-    # The format is `local:remote`, where `local` is the path to the file on the local machine
-    # and `remote` is the path to the file in the container.
     #
     # They will be uploaded from the local repo to the host and then mounted.
-    #
     # ERB files will be evaluated before being copied.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
     files:
       - config/my.cnf.erb:/etc/mysql/my.cnf
-      - config/myoptions.cnf:/etc/mysql/myoptions.cnf
+      - config/myoptions.cnf:/etc/mysql/myoptions.cnf:ro
+      - config/certs:/etc/mysql/certs:ro,Z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    files:
+      - local: config/secret.key
+        remote: /etc/mysql/secret.key
+        mode: "0600"
+        owner: "mysql:mysql"
+      - local: config/ca-cert.pem
+        remote: /etc/mysql/certs/ca-cert.pem
+        mode: "0644"
+        owner: "1000:1000"
+        options: "Z"
 
     # Directories
     #
     # You can specify directories to mount into the container. They will be created on the host
-    # before being mounted:
+    # before being mounted.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
     directories:
       - mysql-logs:/var/log/mysql
+      - mysql-data:/var/lib/mysql:z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    directories:
+      - local: mysql-data
+        remote: /var/lib/mysql
+        mode: "0750"
+        owner: "mysql:mysql"
+      - local: mysql-logs
+        remote: /var/log/mysql
+        mode: "0755"
+        options: "z"
 
     # Volumes
     #

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

@@ -4,16 +4,18 @@
 #
 # Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.
 
-# Fixed group sizes
-#
-# Here, we boot 2 hosts at a time with a 10-second gap between each group:
 boot:
-  limit: 2
-  wait: 10
 
-# Percentage of hosts
-#
-# Here, we boot 25% of the hosts at a time with a 2-second gap between each group:
-boot:
+  # The number or percentage of hosts to boot at a time.
+  # This can be an integer (e.g., 3) or a percentage string (e.g., 25%).
   limit: 25%
-  wait: 2
+
+  # The number of seconds to wait between booting each group of hosts.
+  wait: 10
+
+  # Whether to boot roles in parallel on a host.
+  #
+  # If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.
+  #
+  # Defaults to false.
+  parallel_roles: true