dash 3.2.0 → 4.0.0

data/lib/dash/commands/proxy.rb

@@ -0,0 +1,375 @@
+class Dash::Commands::Proxy < Dash::Commands::Base
+  include Dash::Commands::Proxy::CertTransfer
+
+  delegate :argumentize, :optionize, to: Dash::Utils
+  attr_reader :proxy_run_config
+
+  CONFIG_DIGEST_LABEL = "org.dash.proxy-config-digest"
+
+  # Containers booted before the stage-3b rename carry the old key. New ones are
+  # labelled with CONFIG_DIGEST_LABEL only, but reads fall back to the legacy key
+  # so upgrading doesn't read as config drift and reboot every proxy for nothing.
+  # Both the legacy constant and the fallback go away in stage 3d.
+  LEGACY_CONFIG_DIGEST_LABEL = "org.kamal.proxy-config-digest"
+
+  CONFIG_DIGEST_FORMAT = "'{{ with index .Config.Labels \"#{CONFIG_DIGEST_LABEL}\" }}{{ . }}" \
+    "{{ else }}{{ index .Config.Labels \"#{LEGACY_CONFIG_DIGEST_LABEL}\" }}{{ end }}'"
+
+  def initialize(config, host:)
+    super(config)
+    @proxy_run_config = config.proxy_run(host)
+  end
+
+  def run(digest: nil, name: nil)
+    if proxy_run_config
+      docker \
+        :run,
+        "--name", name || container_name,
+        *proxy_run_config.network_args,
+        "--detach",
+        "--restart", "unless-stopped",
+        "--volume", "dash-proxy-config:/home/dash-proxy/.config/dash-proxy",
+        *config_digest_label_args(digest),
+        *proxy_run_config.docker_options_args,
+        *proxy_run_config.image,
+        *proxy_run_config.run_command
+    else
+      pipe boot_config, xargs(docker_run(digest: digest))
+    end
+  end
+
+  # Stage 3c migrations. All three are idempotent and guarded on the
+  # destination not existing, so a second deploy is a no-op. Stage 3d deletes
+  # them along with the legacy constants they read.
+
+  # Copies the pre-rename config volume into the new one, before anything
+  # starts. The volume holds the routing table and the ACME account and
+  # certificate cache; losing it means re-issuing every certificate and
+  # spending Let's Encrypt rate limits to get back where we were.
+  #
+  # Runs in the dash-proxy image itself — already pulled by this point in the
+  # boot sequence, and its ubuntu base has sh and cp. `--user root` because the
+  # image's own user cannot write the destination volume; `cp -a` preserves the
+  # uid, which the rename leaves at 1001.
+  # The guard is negated and leads the chain, with `|| true` last, because
+  # shell `&&` and `||` share precedence and associate left: written as
+  # `exists || legacy_exists && create && copy` it would parse as
+  # `((exists || legacy_exists) && create) && copy` and re-copy the legacy
+  # volume over live state on every deploy. Leading with `! exists` makes the
+  # whole chain a single left-associative AND, which short-circuits correctly.
+  def copy_legacy_config_volume(volume: Dash::Configuration::Proxy::CONFIG_VOLUME, legacy: Dash::Configuration::Proxy::LEGACY_CONFIG_VOLUME)
+    any \
+      combine(
+        negate(volume_exists(volume)),
+        volume_exists(legacy),
+        docker(:volume, :create, volume),
+        copy_between_volumes(legacy, volume)
+      ),
+      [ :true ]
+  end
+
+  # Stops and removes a pre-rename proxy container so the renamed one can claim
+  # ports 80/443. No port-holder handoff spans two container names, which is
+  # why this stage accepts a brief outage per host.
+  def remove_legacy_container(timeout: nil)
+    any \
+      combine(
+        container_exists(Dash::Configuration::Proxy::LEGACY_CONTAINER_NAME),
+        docker(:container, :stop, *("--time=#{timeout}" if timeout), Dash::Configuration::Proxy::LEGACY_CONTAINER_NAME),
+        docker(:container, :rm, Dash::Configuration::Proxy::LEGACY_CONTAINER_NAME)
+      ),
+      [ :true ]
+  end
+
+  def remove_legacy_holder_container
+    any \
+      combine(
+        container_exists(Dash::Configuration::Proxy::LEGACY_HOLDER_CONTAINER_NAME),
+        docker(:container, :rm, "--force", Dash::Configuration::Proxy::LEGACY_HOLDER_CONTAINER_NAME)
+      ),
+      [ :true ]
+  end
+
+  def start
+    docker :container, :start, container_name
+  end
+
+  def stop(name: container_name, timeout: nil)
+    docker :container, :stop, *("--time #{timeout}" if timeout), name
+  end
+
+  def start_or_run(digest: nil)
+    combine start, run(digest: digest), by: "||"
+  end
+
+  def info
+    docker :ps, "--filter", "'name=^#{container_name}$'"
+  end
+
+  def version
+    pipe \
+      docker(:inspect, container_name, "--format '{{.Config.Image}}'"),
+      [ :awk, "-F:", "'{print \$NF}'" ]
+  end
+
+  def config_digest
+    docker :inspect, container_name, "--format", CONFIG_DIGEST_FORMAT
+  end
+
+  def container_id(only_running: false)
+    container_id_for(container_name: container_name, only_running: only_running)
+  end
+
+  def pull
+    if proxy_run_config
+      docker :pull, proxy_run_config.image
+    else
+      docker :pull, "#{substitute(read_image)}:#{substitute(read_image_version)}"
+    end
+  end
+
+  def list(name: container_name, json: false)
+    docker :exec, name, "dash-proxy", :list, *("--json" if json)
+  end
+
+  def cache_stats(count: false, json: false)
+    docker :exec, container_name, "dash-proxy", :cache, :stats, *optionize({ count: count || nil, json: json || nil }.compact)
+  end
+
+  def cache_purge(service, path_prefix: nil)
+    docker :exec, container_name, "dash-proxy", :cache, :purge, service, *optionize({ "path-prefix": path_prefix }.compact)
+  end
+
+  # One mount destination per line - what the running container was actually
+  # booted with, as opposed to what the current configuration would mount.
+  def mount_destinations
+    docker :inspect, container_name, "--format", "'{{range .Mounts}}{{println .Destination}}{{end}}'"
+  end
+
+  # Zero-downtime handoff commands (proxy/run port_holder mode)
+
+  def port_holder?
+    proxy_run_config&.port_holder? || false
+  end
+
+  def next_container_name
+    "#{container_name}-next"
+  end
+
+  def run_holder
+    docker \
+      :run,
+      "--name", proxy_run_config.holder_container_name,
+      "--network", "dash",
+      "--detach",
+      "--restart", "unless-stopped",
+      *proxy_run_config.holder_docker_args,
+      *proxy_run_config.image,
+      "dash-proxy", "hold"
+  end
+
+  def start_holder_or_run
+    combine docker(:container, :start, proxy_run_config.holder_container_name), run_holder, by: "||"
+  end
+
+  def holder_container_id
+    container_id_for(container_name: proxy_run_config.holder_container_name, only_running: true)
+  end
+
+  # Cancel the restart policy before draining: drain makes the proxy exit on
+  # its own, which - unlike `docker stop` - an active restart policy would undo.
+  def disable_restart
+    docker :update, "--restart=no", container_name
+  end
+
+  def drain(timeout: nil)
+    docker :exec, container_name, "dash-proxy", :drain, *("--drain-timeout=#{timeout}s" if timeout)
+  end
+
+  def wait_for_exit(name: container_name)
+    docker :wait, name
+  end
+
+  def remove_stopped_container(name: container_name)
+    docker :container, :rm, name
+  end
+
+  def promote_next_container
+    docker :container, :rename, next_container_name, container_name
+  end
+
+  def logs(timestamps: true, since: nil, lines: nil, grep: nil, grep_options: nil)
+    pipe \
+      docker(:logs, container_name, ("--since #{since}" if since), ("--tail #{lines}" if lines), ("--timestamps" if timestamps), "2>&1"),
+      ("grep '#{grep}'#{" #{grep_options}" if grep_options}" if grep)
+  end
+
+  def follow_logs(host:, timestamps: true, grep: nil, grep_options: nil)
+    run_over_ssh pipe(
+      docker(:logs, container_name, ("--timestamps" if timestamps), "--tail", "10", "--follow", "2>&1"),
+      (%(grep "#{grep}"#{" #{grep_options}" if grep_options}) if grep)
+    ).join(" "), host: host
+  end
+
+  # `retry` takes a host, or --all; the rest take no arguments.
+  def domains(subcommand, *args)
+    docker :exec, container_name, "dash-proxy", "domains", subcommand, *args
+  end
+
+  # Docker ANDs multiple `--filter label=` values, so matching both the current
+  # and the pre-rename image title takes two commands rather than one filter
+  # with two values. Without the legacy pass, `dash proxy remove` on a host that
+  # has not yet been through the rename silently leaves the old container and
+  # image behind. Stage 3d drops the legacy half.
+  def remove_container
+    combine \
+      prune_containers_titled(Dash::Configuration::Proxy::IMAGE_TITLE),
+      prune_containers_titled(Dash::Configuration::Proxy::LEGACY_IMAGE_TITLE)
+  end
+
+  def remove_image
+    combine \
+      prune_images_titled(Dash::Configuration::Proxy::IMAGE_TITLE),
+      prune_images_titled(Dash::Configuration::Proxy::LEGACY_IMAGE_TITLE)
+  end
+
+  def cleanup_traefik
+    chain \
+      docker(:container, :stop, "traefik"),
+      combine(
+        docker(:container, :prune, "--force", "--filter", "label=org.opencontainers.image.title=Traefik"),
+        docker(:image, :prune, "--all", "--force", "--filter", "label=org.opencontainers.image.title=Traefik")
+      )
+  end
+
+  def ensure_proxy_directory
+    make_directory config.proxy_boot.host_directory
+  end
+
+  def remove_proxy_directory
+    remove_directory config.proxy_boot.host_directory
+  end
+
+  def ensure_apps_config_directory
+    make_directory config.proxy_boot.apps_directory
+  end
+
+  # Static path rather than proxy_run_config.secrets_path: the file must be
+  # removable precisely when the run config (or its secrets) is gone.
+  def remove_proxy_secrets_file
+    remove_file File.join(config.proxy_boot.host_directory, Dash::Configuration::Proxy::Run::SECRETS_FILENAME)
+  end
+
+  def boot_config
+    [ :echo, "#{substitute(read_boot_options)} #{substitute(read_image)}:#{substitute(read_image_version)} #{substitute(read_run_command)}" ]
+  end
+
+  def read_boot_options
+    read_file(config.proxy_boot.options_file, default: config.proxy_boot.default_boot_options.join(" "))
+  end
+
+  def read_image
+    read_file(config.proxy_boot.image_file, default: config.proxy_boot.image_default)
+  end
+
+  def read_image_version
+    read_file(config.proxy_boot.image_version_file, default: Dash::Configuration::Proxy::Run::MINIMUM_VERSION)
+  end
+
+  def read_run_command
+    read_file(config.proxy_boot.run_command_file)
+  end
+
+  def reset_boot_options
+    remove_file config.proxy_boot.options_file
+  end
+
+  def reset_image
+    remove_file config.proxy_boot.image_file
+  end
+
+  def reset_image_version
+    remove_file config.proxy_boot.image_version_file
+  end
+
+  def reset_run_command
+    remove_file config.proxy_boot.run_command_file
+  end
+
+  def loadbalancer
+    @loadbalancer ||= Dash::Commands::Loadbalancer.new(config, loadbalancer_config: DASH.loadbalancer_config)
+  end
+
+  private
+    def container_name
+      config.proxy_boot.container_name
+    end
+
+    def cert_store_volume_args
+      [ "--volume", "dash-proxy-config:/home/dash-proxy/.config/dash-proxy" ]
+    end
+
+    # Same fallback as #pull: without a run config the image comes from the
+    # legacy boot config files on the host.
+    def one_off_image
+      if proxy_run_config
+        [ proxy_run_config.image ]
+      else
+        [ "#{substitute(read_image)}:#{substitute(read_image_version)}" ]
+      end
+    end
+
+    def config_digest_label_args(digest)
+      [ "--label", "#{CONFIG_DIGEST_LABEL}=#{digest}" ] if digest
+    end
+
+    def negate(command)
+      [ "!", *command ]
+    end
+
+    def volume_exists(name)
+      docker :volume, :inspect, name, ">", "/dev/null", "2>&1"
+    end
+
+    def container_exists(name)
+      docker :container, :inspect, name, ">", "/dev/null", "2>&1"
+    end
+
+    def copy_between_volumes(from, to)
+      docker \
+        :run, "--rm", "--user", "root", "--entrypoint", "sh",
+        "--volume", "#{from}:/from",
+        "--volume", "#{to}:/to",
+        proxy_image,
+        "-c", "'cp -a /from/. /to/'"
+    end
+
+    # The image the volume copy borrows. The proxy this gem is pinned to is
+    # already pulled by the time the copy runs, and `rake release` gates on
+    # MINIMUM_VERSION being published, so this is always resolvable — unlike
+    # the legacy boot path's image, which is read from a file on the host.
+    def proxy_image
+      proxy_run_config&.image ||
+        "#{config.proxy_boot.image_default}:#{Dash::Configuration::Proxy::Run::MINIMUM_VERSION}"
+    end
+
+    def prune_containers_titled(title)
+      docker :container, :prune, "--force", "--filter", "label=org.opencontainers.image.title=#{title}"
+    end
+
+    def prune_images_titled(title)
+      docker :image, :prune, "--all", "--force", "--filter", "label=org.opencontainers.image.title=#{title}"
+    end
+
+    def docker_run(digest: nil)
+      docker \
+        :run,
+        "--name", container_name,
+        "--network", "dash",
+        "--detach",
+        "--restart", "unless-stopped",
+        "--volume", "dash-proxy-config:/home/dash-proxy/.config/dash-proxy",
+        *config_digest_label_args(digest),
+        *config.proxy_boot.apps_volume.docker_args
+    end
+end

data/lib/{kamal → dash}/commands/prune.rb

@@ -1,7 +1,7 @@
 require "active_support/duration"
 require "active_support/core_ext/numeric/time"
 
-class Kamal::Commands::Prune < Kamal::Commands::Base
+class Dash::Commands::Prune < Dash::Commands::Base
   def dangling_images
     docker :image, :prune, "--force", "--filter", "label=service=#{config.service}"
   end
@@ -15,7 +15,7 @@ class Kamal::Commands::Prune < Kamal::Commands::Base
 
   # Scoped to one role so a busy sibling role cannot push another role's newest
   # container past the retain window. That matters beyond disk hygiene: a
-  # container kamal-proxy has put to sleep is `exited`, so it is a removal
+  # container dash-proxy has put to sleep is `exited`, so it is a removal
   # candidate, and once it is gone every wake 404s. With `retain >= 1` a role's
   # newest container always survives, and the slept one is always the newest —
   # sleeping happens to the current release.

data/lib/dash/commands/registry.rb

@@ -0,0 +1,44 @@
+class Dash::Commands::Registry < Dash::Commands::Base
+  LOCAL_CONTAINER_NAME = "dash-docker-registry"
+  LEGACY_LOCAL_CONTAINER_NAME = "kamal-docker-registry"
+
+  def login(registry_config: nil)
+    registry_config ||= config.registry
+
+    return if registry_config.local?
+
+    docker :login,
+      registry_config.server,
+      "-u", sensitive(Dash::Utils.escape_shell_value(registry_config.username)),
+      "-p", sensitive(Dash::Utils.escape_shell_value(registry_config.password))
+  end
+
+  def logout(registry_config: nil)
+    registry_config ||= config.registry
+
+    docker :logout, registry_config.server
+  end
+
+  def setup(registry_config: nil)
+    registry_config ||= config.registry
+
+    combine \
+      docker(:start, LOCAL_CONTAINER_NAME),
+      docker(:run, "--detach", "-p", "127.0.0.1:#{registry_config.local_port}:5000", "--name", LOCAL_CONTAINER_NAME, "registry:3"),
+      by: "||"
+  end
+
+  # The legacy container is torn down alongside the current one so an operator's
+  # laptop doesn't keep a stray kamal-docker-registry holding the local port
+  # after upgrading. Dash::Cli::Registry#remove already runs this with
+  # raise_on_non_zero_exit: false, so a missing container of either name is fine.
+  def remove
+    chain \
+      combine(docker(:stop, LOCAL_CONTAINER_NAME), docker(:rm, LOCAL_CONTAINER_NAME)),
+      combine(docker(:stop, LEGACY_LOCAL_CONTAINER_NAME), docker(:rm, LEGACY_LOCAL_CONTAINER_NAME))
+  end
+
+  def local?
+    config.registry.local?
+  end
+end

data/lib/{kamal → dash}/commands/server.rb

@@ -1,8 +1,4 @@
-class Kamal::Commands::Server < Kamal::Commands::Base
-  def ensure_run_directory
-    make_directory config.run_directory
-  end
-
+class Dash::Commands::Server < Dash::Commands::Base
   def remove_app_directory
     remove_directory config.app_directory
   end

data/lib/dash/commands.rb

@@ -0,0 +1,2 @@
+module Dash::Commands
+end

data/lib/{kamal → dash}/configuration/accessory.rb

@@ -1,9 +1,9 @@
-class Kamal::Configuration::Accessory
-  include Kamal::Configuration::Validation
+class Dash::Configuration::Accessory
+  include Dash::Configuration::Validation
 
-  DEFAULT_NETWORK = "kamal"
+  DEFAULT_NETWORK = "dash"
 
-  delegate :argumentize, :optionize, to: Kamal::Utils
+  delegate :argumentize, :optionize, to: Dash::Utils
 
   attr_reader :name, :env, :proxy, :registry
 
@@ -14,7 +14,7 @@ class Kamal::Configuration::Accessory
       accessory_config,
       example: validation_yml["accessories"]["mysql"],
       context: "accessories/#{name}",
-      with: Kamal::Configuration::Validator::Accessory
+      with: Dash::Configuration::Validator::Accessory
 
     ensure_valid_roles
 
@@ -121,17 +121,17 @@ class Kamal::Configuration::Accessory
     attr_reader :config, :accessory_config
 
     def initialize_env
-      Kamal::Configuration::Env.new \
+      Dash::Configuration::Env.new \
         config: accessory_config.fetch("env", {}),
         secrets: config.secrets,
         context: "accessories/#{name}/env"
     end
 
     # The load balancer fans the app's own service out to role targets only
-    # (see Kamal::Cli::Proxy#loadbalancer), so an accessory is never behind it
-    # and must keep the host/TLS it registers with kamal-proxy directly.
+    # (see Dash::Cli::Proxy#loadbalancer), so an accessory is never behind it
+    # and must keep the host/TLS it registers with dash-proxy directly.
     def initialize_proxy
-      Kamal::Configuration::Proxy.new \
+      Dash::Configuration::Proxy.new \
         config: config,
         proxy_config: accessory_config["proxy"],
         context: "accessories/#{name}/proxy",
@@ -140,7 +140,7 @@ class Kamal::Configuration::Accessory
     end
 
     def initialize_registry
-      Kamal::Configuration::Registry.new \
+      Dash::Configuration::Registry.new \
         config: accessory_config,
         secrets: config.secrets,
         context: "accessories/#{name}/registry"
@@ -187,7 +187,7 @@ class Kamal::Configuration::Accessory
 
     def path_volumes(paths)
       paths.map do |local, config|
-        Kamal::Configuration::Volume.new \
+        Dash::Configuration::Volume.new \
           host_path: config[:host_path],
           container_path: config[:container_path],
           options: config[:options]
@@ -273,9 +273,9 @@ class Kamal::Configuration::Accessory
 
     def ensure_valid_roles
       if accessory_config["roles"] && (missing_roles = accessory_config["roles"] - config.roles.map(&:name)).any?
-        raise Kamal::ConfigurationError, "accessories/#{name}: unknown roles #{missing_roles.join(", ")}"
+        raise Dash::ConfigurationError, "accessories/#{name}: unknown roles #{missing_roles.join(", ")}"
       elsif accessory_config["role"] && !config.role(accessory_config["role"])
-        raise Kamal::ConfigurationError, "accessories/#{name}: unknown role #{accessory_config["role"]}"
+        raise Dash::ConfigurationError, "accessories/#{name}: unknown role #{accessory_config["role"]}"
       end
     end
 end

data/lib/{kamal → dash}/configuration/alias.rb

@@ -1,5 +1,5 @@
-class Kamal::Configuration::Alias
-  include Kamal::Configuration::Validation
+class Dash::Configuration::Alias
+  include Dash::Configuration::Validation
 
   attr_reader :name, :command
 
@@ -10,6 +10,6 @@ class Kamal::Configuration::Alias
       command,
       example: validation_yml["aliases"]["uname"],
       context: "aliases/#{name}",
-      with: Kamal::Configuration::Validator::Alias
+      with: Dash::Configuration::Validator::Alias
   end
 end

data/lib/{kamal → dash}/configuration/boot.rb

@@ -1,5 +1,5 @@
-class Kamal::Configuration::Boot
-  include Kamal::Configuration::Validation
+class Dash::Configuration::Boot
+  include Dash::Configuration::Validation
 
   attr_reader :boot_config
 

data/lib/{kamal → dash}/configuration/builder.rb

@@ -1,5 +1,5 @@
-class Kamal::Configuration::Builder
-  include Kamal::Configuration::Validation
+class Dash::Configuration::Builder
+  include Dash::Configuration::Validation
 
   attr_reader :config, :builder_config
   delegate :image, :service, to: :config
@@ -12,7 +12,7 @@ class Kamal::Configuration::Builder
     @server = config.registry.server
     @service = config.service
 
-    validate! builder_config, with: Kamal::Configuration::Validator::Builder
+    validate! builder_config, with: Dash::Configuration::Validator::Builder
   end
 
   def to_h
@@ -31,7 +31,7 @@ class Kamal::Configuration::Builder
     @local_arches ||= if local_disabled?
       []
     elsif remote
-      arches & [ Kamal::Utils.docker_arch ]
+      arches & [ Dash::Utils.docker_arch ]
     else
       arches
     end
@@ -136,7 +136,7 @@ class Kamal::Configuration::Builder
   end
 
   def git_clone?
-    Kamal::Git.used? && builder_config["context"].nil?
+    Dash::Git.used? && builder_config["context"].nil?
   end
 
   def clone_directory
@@ -201,11 +201,11 @@ class Kamal::Configuration::Builder
     end
 
     def repo_basename
-      File.basename(Kamal::Git.root)
+      File.basename(Dash::Git.root)
     end
 
     def repo_relative_pwd
-      Dir.pwd.delete_prefix(Kamal::Git.root)
+      Dir.pwd.delete_prefix(Dash::Git.root)
     end
 
     def pwd_sha

data/lib/{kamal → dash}/configuration/docs/accessory.yml

@@ -150,7 +150,7 @@ accessories:
     #
     # The network the accessory will be attached to.
     #
-    # Defaults to kamal:
+    # Defaults to dash:
     network: custom
 
     # Proxy
@@ -160,12 +160,12 @@ accessories:
     # app-level `proxy:` (see `dash docs proxy`), though root-only keys such as
     # `loadbalancer` and `reboot_on_deploy` have no effect inside an accessory.
     # Declaring a proxy here makes the accessory's hosts proxy hosts:
-    # `dash proxy boot` (and `dash deploy`) will run kamal-proxy on them
+    # `dash proxy boot` (and `dash deploy`) will run dash-proxy on them
     # automatically.
     #
     # Accessories are never load balanced. The loadbalancer fans the app's own
     # service out to its role targets, so an accessory always registers its
-    # hostname and TLS with the kamal-proxy on its own host — whether or not the
+    # hostname and TLS with the dash-proxy on its own host — whether or not the
     # loadbalancer is active for the app. Point the accessory's DNS record at the
     # accessory host, not at the loadbalancer.
     #

data/lib/{kamal → dash}/configuration/docs/builder.yml

@@ -19,13 +19,13 @@ builder:
 
   # Remote
   #
-  # The connection string for a remote builder. If supplied, Kamal will use this
+  # The connection string for a remote builder. If supplied, dash will use this
   # for builds that do not match the local architecture of the deployment host.
   remote: ssh://docker@docker-builder
 
   # Local
   #
-  # If set to false, Kamal will always use the remote builder even when building
+  # If set to false, dash will always use the remote builder even when building
   # the local architecture.
   #
   # Defaults to true:
@@ -87,7 +87,7 @@ builder:
 
   # Build secrets
   #
-  # Values are read from `.kamal/secrets`:
+  # Values are read from `.dash/secrets`:
   secrets:
     - SECRET1
     - SECRET2