dash 4.0.8 → 4.1.1

data/lib/dash/cli/report.rb

@@ -0,0 +1,97 @@
+require "json"
+
+# Reads the JSON reports every deploy leaves under `.dash/reports`.
+#
+# Entirely local and read-only: no lock, no SSH, nothing that can change a server. It is
+# the command to reach for after a deploy has finished and the table has scrolled away,
+# and the one that answers "was it always this slow?".
+class Dash::Cli::Report < Dash::Cli::Base
+  default_command :show
+
+  TREND_HEADINGS = %w[ started version total build boot advice ].freeze
+  COLUMNS = "  %-20s %-10s %8s %8s %8s  %s".freeze
+
+  desc "show", "Print the last saved deploy report"
+  option :last, type: :numeric, banner: "N", desc: "Print a trend table over the last N reports instead"
+  def show
+    if (last = options[:last])
+      return say "--last takes a positive number of reports, got #{last}", :red unless count?(last)
+
+      print_trend saved.recent(last.to_i)
+    else
+      print_latest saved.recent(1).first
+    end
+  end
+
+  desc "path", "Print the directory saved reports are written to"
+  def path
+    puts reports_directory
+  end
+
+  private
+    # Thor's :numeric happily hands over -1 or 2.5, which Array#first turns into a
+    # backtrace. A typo in a flag deserves a sentence, not a stack trace.
+    def count?(value)
+      value.to_i == value && value.to_i > 0
+    end
+
+    def saved
+      Dash::Report::History.new(reports_directory, destination: DASH.config.destination)
+    end
+
+    def print_latest(document)
+      return say_nothing_saved unless document
+
+      say "Deploy report for #{subject}", :magenta
+      puts summary_line(document)
+      puts Dash::Report.from_h(document).lines
+    end
+
+    def print_trend(documents)
+      return say_nothing_saved if documents.empty?
+
+      say "Last #{documents.size} #{"report".pluralize(documents.size)} for #{subject}", :magenta
+      puts format(COLUMNS, *TREND_HEADINGS)
+      documents.reverse_each { |document| puts trend_row(document) }
+    end
+
+    def subject
+      [ DASH.config.service, ("to #{DASH.config.destination}" if DASH.config.destination) ].compact.join(" ")
+    end
+
+    def summary_line(document)
+      "  #{document[:command]} #{document[:status]} in #{seconds(document[:runtime])} at #{document[:started_at]}" \
+        "#{" (version #{document[:version]})" if document[:version]}#{error_note(document)}"
+    end
+
+    def error_note(document)
+      " — #{document.dig(:error, :class)}: #{document.dig(:error, :message)}" if document[:error]
+    end
+
+    def trend_row(document)
+      format COLUMNS, document[:started_at], (document[:version] || "").to_s[0...10],
+        seconds(document[:runtime]), phase(document, Dash::Report::Trends::BUILD_PHASE),
+        phase(document, Dash::Report::Trends::BOOT_PHASE), advice_count(document)
+    end
+
+    def phase(document, name)
+      found = Array(document[:phases]).find { |candidate| candidate[:name] == name && candidate[:depth].to_i.zero? }
+
+      found ? seconds(found[:seconds]) : "-"
+    end
+
+    def advice_count(document)
+      findings = Array(document[:advice])
+      warnings = findings.count { |finding| finding[:severity] == "warn" }
+
+      "#{findings.size}#{" (#{warnings} warn)" if warnings > 0}"
+    end
+
+    def seconds(value)
+      format("%.1fs", value.to_f)
+    end
+
+    def say_nothing_saved
+      say "No saved reports for #{subject} in #{reports_directory}", :yellow
+    end
+end

data/lib/dash/cli/templates/sample_hooks/post-deploy.sample

@@ -10,5 +10,10 @@
 # DASH_ROLES (if set)
 # DASH_DESTINATION (if set)
 # DASH_RUNTIME
+# DASH_BUILD_RUNTIME (if the deploy built an image)
+# DASH_BOOT_RUNTIME (if the deploy booted containers)
+# DASH_ADVICE_COUNT
+# DASH_ADVICE_WARNINGS
+# DASH_REPORT_PATH (unless report/history is 0)
 
 echo "$DASH_PERFORMER deployed $DASH_VERSION to $DASH_DESTINATION in $DASH_RUNTIME seconds"

data/lib/dash/commander.rb

@@ -6,7 +6,13 @@ require "active_support/notifications"
 
 class Dash::Commander
   attr_accessor :verbosity, :holding_lock, :holding_server_lock, :connected, :logging, :lock_wait, :lock_wait_timeout, :lock_wait_interval
-  attr_reader :specific_roles, :specific_hosts, :timings
+  attr_reader :specific_roles, :specific_hosts, :timings, :report
+
+  # Hosts whose run directory this process has already swept, so the second lock acquire
+  # of a command does not re-run the migration everywhere. Per host rather than a flag:
+  # `dash upgrade` narrows the host set between acquires, and a host that was never in
+  # scope has never been swept.
+  attr_reader :run_directory_ensured_on
   delegate :hosts, :roles, :primary_host, :primary_role, :roles_on, :app_hosts, :proxy_hosts, :accessory_hosts, to: :specifics
 
   def initialize
@@ -24,10 +30,12 @@ class Dash::Commander
     self.lock_wait_interval = 15
     @modify_depth = 0
     @timings = Dash::Timings.new
+    @report = Dash::Report.new(timings: @timings)
     @specifics = @specific_roles = @specific_hosts = nil
     @config = @config_kwargs = nil
     @output_logger = nil
     @commands = {}
+    @run_directory_ensured_on = []
   end
 
   def config
@@ -170,7 +178,7 @@ class Dash::Commander
     @logging = true
     if modify_started
       ActiveSupport::Notifications.instrument("modify.kamal",
-        command: command, subcommand: subcommand, destination: config.destination, hosts: hosts) { yield }
+        command: command, subcommand: subcommand, destination: config.destination, hosts: hosts, report: report) { yield }
     else
       yield
     end

data/lib/dash/commands/app.rb

@@ -3,6 +3,16 @@ class Dash::Commands::App < Dash::Commands::Base
 
   ACTIVE_DOCKER_STATUSES = [ :running, :restarting ]
 
+  # Separates the two answers #boot_state and #stale_state return. A container id is hex
+  # and a version is a name suffix, so neither can produce this line on its own.
+  BOOT_STATE_SEPARATOR = "--%--"
+
+  # The two halves of a #boot_state or #stale_state capture, raw. Callers decide what an
+  # empty half means; the separator line itself is dropped.
+  def self.split_state(output)
+    output.to_s.partition(/^#{Regexp.escape(BOOT_STATE_SEPARATOR)}$/).values_at(0, 2)
+  end
+
   attr_reader :role, :host
 
   delegate :container_name, to: :role
@@ -50,6 +60,31 @@ class Dash::Commands::App < Dash::Commands::Base
     docker :exec, container_name(version), *shell([ role.healthcheck.exec ])
   end
 
+  # Waits on the host for the container to reach a status the poller accepts, so a boot
+  # pays one round trip for the wait however long the container takes to come up - the
+  # client-side poll paid one per attempt. Prints the status it stopped on to stdout: the
+  # moment it sees one of READY_STATUSES, or the last one it saw when the deadline passes.
+  # Progress goes to stderr once a second in between. Waiting through every other status is
+  # deliberate: docker reports a container `unhealthy` after three failed probes, which for
+  # an app slower than that is a state it recovers from.
+  #
+  # Reaching the deadline exits 0, because it is an answer - the poller phrases it. Only a
+  # status that could not be read at all exits non-zero, which is a broken command and
+  # SSHKit's to raise, exactly as it was when the read was a round trip of its own.
+  def wait_for_ready(version:, timeout:)
+    shell [
+      "started=$(date +%s);",
+      "while true; do",
+      *readiness_probe(version: version),
+      "case \"$status\" in #{READY_STATUSES.join("|")}) echo \"$status\"; exit 0;; esac;",
+      "elapsed=$(( $(date +%s) - started ));",
+      "if [ \"$elapsed\" -ge #{timeout.to_i} ]; then echo \"$status\"; exit 0; fi;",
+      "echo \"#{READINESS_PROGRESS_PREFIX} $elapsed $(( #{timeout.to_i} - elapsed )) $status\" 1>&2;",
+      "sleep 1;",
+      "done"
+    ]
+  end
+
   def stop(version: nil)
     pipe \
       version ? container_id_for_version(version) : current_running_container_id,
@@ -75,6 +110,30 @@ class Dash::Commands::App < Dash::Commands::Base
       extract_version_from_name
   end
 
+  # Everything a boot needs to know about a host before it starts anything: whether a
+  # container for the version being deployed already exists (so it can be renamed out of
+  # the way) and which version is running now (so it can be stopped once the new one is
+  # live). Two questions, one round trip, answers split on BOOT_STATE_SEPARATOR.
+  #
+  # Chained with `;` rather than `&&`: an empty answer to either is a normal result, not
+  # a failure, and the second question must be asked whatever the first one said.
+  def boot_state(version)
+    chain \
+      container_id_for_version(version),
+      [ :echo, BOOT_STATE_SEPARATOR ],
+      current_running_version
+  end
+
+  # Everything the stale check needs from a host: every version of the role that has a
+  # container, and the version running now - the difference is what is stale. Same shape
+  # as #boot_state, same separator, same reason for `;` over `&&`.
+  def stale_state
+    chain \
+      list_versions,
+      [ :echo, BOOT_STATE_SEPARATOR ],
+      current_running_version
+  end
+
   def list_versions(*docker_args, statuses: nil)
     pipe \
       docker(:ps, *container_filter_args(statuses: statuses), *docker_args, "--format", '"{{.Names}}"'),
@@ -86,6 +145,28 @@ class Dash::Commands::App < Dash::Commands::Base
   end
 
   private
+    # The same two readiness sources #status and #health_probe cover, read into `$status`
+    # so the loop around them is the same either way. They differ in what a non-zero exit
+    # means. A probe that exits non-zero IS the answer "not ready", so its output is
+    # discarded and the loop goes on; an inspect that produced no answer at all - docker is
+    # unreachable, or the container is gone - takes the whole command down with it, with
+    # docker's complaint on stderr for SSHKit to put in the exception.
+    #
+    # An empty status is checked as well as the exit code, because the exit code alone is
+    # not portable: the read is a pipeline, so its status is xargs', and a `docker container
+    # ls` that failed pipes nothing. GNU xargs then runs `docker inspect` with no container
+    # and exits 123, but BSD and BusyBox xargs skip the utility entirely and exit 0. Both
+    # leave `$status` empty, and empty is not something a working `docker inspect --format`
+    # can print.
+    def readiness_probe(version:)
+      if role.healthcheck&.exec?
+        [ "if", *health_probe(version: version), ">/dev/null 2>&1;", "then status=healthy;", "else status=\"#{EXEC_PROBE_FAILED}\";", "fi;" ]
+      else
+        [ "status=#{substitute(*status(version: version))} || exit $?;",
+          "if [ -z \"$status\" ]; then echo \"could not read the status of #{container_name(version)}\" 1>&2; exit 1; fi;" ]
+      end
+    end
+
     def latest_image_id
       docker :image, :ls, *argumentize("--filter", "reference=#{config.latest_image}"), "--format", "'{{.ID}}'"
     end

data/lib/dash/commands/auditor.rb

@@ -14,6 +14,16 @@ class Dash::Commands::Auditor < Dash::Commands::Base
       append([ :echo, escape_shell_value(audit_line(line, **details)) ], audit_log_file)
   end
 
+  # The audit line and the action it describes in one round trip, still in that order:
+  # the log is written first, and `&&` means a failed write aborts the action exactly as
+  # a failed standalone audit would have.
+  #
+  # Only ever fold in commands the caller would `execute`. A `capture` folded in here
+  # would come back with nothing to distinguish the audit's own output from the answer.
+  def record_then(line, *commands, **details)
+    combine record(line, **details), *commands
+  end
+
   def reveal
     [ :tail, "-n", 50, audit_log_file ]
   end

data/lib/dash/commands/base.rb

@@ -10,6 +10,22 @@ module Dash::Commands
 
     DOCKER_HEALTH_STATUS_FORMAT = "'{{if .State.Health}}{{.State.Health.Status}}{{else}}#{NO_HEALTHCHECK}:{{.State.Status}}{{end}}'"
 
+    # The statuses a boot accepts as ready. Dash::Cli::Healthcheck::Poller decides what a
+    # status means; Dash::Commands::App#wait_for_ready only decides when to stop looking,
+    # and it stops on exactly these. The two must agree: a status the host loop returned
+    # early for that the poller would not accept fails a boot the old client-side poll
+    # would have waited out.
+    READY_STATUSES = [ "healthy", "#{NO_HEALTHCHECK}:running" ].freeze
+
+    # What a `healthcheck: exec:` probe reports when it exits non-zero. Produced by the
+    # host-side wait, read back by the poller, so it is a wire format, not a message.
+    EXEC_PROBE_FAILED = "exec probe exited non-zero"
+
+    # The line #wait_for_ready prints to stderr on every attempt, read back by
+    # Dash::Cli::Healthcheck::ProgressReporter. stderr, because a capture returns stdout
+    # alone - which keeps the captured value the final status and nothing else.
+    READINESS_PROGRESS_PREFIX = "dash-readiness"
+
     attr_accessor :config
 
     def initialize(config)
@@ -24,6 +40,18 @@ module Dash::Commands
       docker :container, :ls, *("--all" unless only_running), "--filter", "'name=^#{container_name}$'", "--quiet"
     end
 
+    # True only when `list_command`'s own output is confirmed empty - never inferred from
+    # a failure. `docker container inspect name > /dev/null 2>&1` (negated) cannot tell
+    # "no such container" from "the daemon could not be asked" - both exit non-zero - so a
+    # transient failure there reads as confirmed absence. A `list` exits 0 whichever way
+    # the match went and non-zero only on a genuine failure, so `result=$(list) && [ -z
+    # "$result" ]` fails closed: `result=$(list)` carries list's own exit status (POSIX;
+    # verified against sh and bash), so a failed list stops the chain before the test runs.
+    # `list_command` must be a listing (docker container/volume ls), never an inspect.
+    def confirmed_empty?(list_command)
+      [ "result=$(#{list_command.join(" ")})", "&&", "[", "-z", "\"$result\"", "]" ]
+    end
+
     def make_directory_for(remote_file)
       make_directory Pathname.new(remote_file).dirname.to_s
     end
@@ -98,6 +126,13 @@ module Dash::Commands
         combine *commands, by: ";"
       end
 
+      # One subshell around an && chain. Composing two builders that each mix && and ||
+      # cannot be done flat - the operators share precedence and associate left, so the
+      # second builder's guards re-associate across the first one's.
+      def group(*commands)
+        [ "(", *combine(*commands), ")" ]
+      end
+
       def pipe(*commands)
         combine *commands, by: "|"
       end
@@ -134,13 +169,19 @@ module Dash::Commands
         any \
           volume_exists(volume),
           negate(volume_exists(legacy)),
-          [ "(", *combine(docker(:volume, :create, volume), copy_between_volumes(legacy, volume, image: image)), ")" ]
+          group(docker(:volume, :create, volume), copy_between_volumes(legacy, volume, image: image))
       end
 
       def negate(command)
         [ "!", *command ]
       end
 
+      # The docker builders (network create, the stage-3c network bridge) for callers that
+      # compose them into a command of their own rather than executing them on their own.
+      def docker_commands
+        @docker_commands ||= Dash::Commands::Docker.new(config)
+      end
+
       def volume_exists(name)
         docker :volume, :inspect, name, ">", "/dev/null", "2>&1"
       end

data/lib/dash/commands/builder/base.rb

@@ -14,9 +14,27 @@ class Dash::Commands::Builder::Base < Dash::Commands::Base
     docker :image, :rm, "--force", config.absolute_image
   end
 
+  # Dropping the old image is housekeeping - a host that never had it is not an error -
+  # so it must not short-circuit whatever it shares a round trip with.
+  #
+  # The `|| true` is parenthesised because `&&` and `||` bind equally and associate left:
+  # ungrouped, an `audit && clean || true && pull` chain lets a FAILED audit fall into the
+  # same `|| true` and pull anyway, exit status 0. The group confines it to the clean.
+  #
+  # Composed only, never executed on its own: SSHKit's command map prefixes an unknown
+  # first word with /usr/bin/env, and the first word here is `(`.
+  def clean_then_pull
+    combine [ "(", *any(clean, [ :true ]), ")" ], pull
+  end
+
   def push(export_action = "registry", tag_as_dirty: false, no_cache: false)
     docker :buildx, :build,
       "--output=type=#{export_action}",
+      # Plain progress is what dash parses into the build rows of the deploy report
+      # (Dash::Build::ProgressParser). buildx already falls back to it when stdout is a
+      # pipe, which it always is under SSHKit — this only pins it so the format cannot
+      # change under us.
+      "--progress=plain",
       *platform_options(arches),
       *([ "--builder", builder_name ] unless docker_driver?),
       *build_tag_options(tag_as_dirty: tag_as_dirty),

data/lib/dash/commands/builder.rb

@@ -2,7 +2,7 @@ require "active_support/core_ext/string/filters"
 
 class Dash::Commands::Builder < Dash::Commands::Base
   delegate \
-    :create, :remove, :dev, :push, :clean, :pull, :info, :inspect_builder,
+    :create, :remove, :dev, :push, :clean, :pull, :clean_then_pull, :info, :inspect_builder,
     :validate_image, :first_mirror, :login_to_registry_locally?, :push_env,
     to: :target
 

data/lib/dash/commands/loadbalancer.rb

@@ -47,6 +47,28 @@ class Dash::Commands::Loadbalancer < Dash::Commands::Base
     copy_legacy_volume(legacy: legacy_config_volume_name, volume: config_volume_name, image: loadbalancer_config.run.image)
   end
 
+  # Everything this host needs before anything reads its container, volume or network,
+  # in the one round trip it already pays for the apps-config directory. Same shape as
+  # Dash::Commands::Proxy#prepare_boot, including why the guard has to be the first word.
+  def prepare_boot
+    combine legacy_rename, ensure_apps_config_directory
+  end
+
+  # The loadbalancer's half of the stage-3c bridge - network, then volume - skipped
+  # outright by a host that has already been through it. No legacy container is replaced
+  # here (a dedicated loadbalancer host never ran one under a name this gem knows), so
+  # the marker is verified on the volume instead: the new one exists, or there was never
+  # a legacy one to adopt. Stage 3d deletes this with the rest of the bridge.
+  def legacy_rename
+    any \
+      [ :test, "-f", legacy_rename_marker ],
+      group(
+        group(docker_commands.connect_legacy_network_containers),
+        group(copy_legacy_config_volume),
+        group(any(mark_legacy_renamed, [ :true ]))
+      )
+  end
+
   def deploy(targets: [])
     docker :exec, container_name, "dash-proxy", "deploy", loadbalancer_config.config.service,
       *loadbalancer_config.deploy_command_args(targets: targets)
@@ -76,6 +98,12 @@ class Dash::Commands::Loadbalancer < Dash::Commands::Base
     docker :inspect, container_name, "--format", Dash::Commands::Proxy::CONFIG_DIGEST_FORMAT
   end
 
+  # One read for container id, image tag and config digest - parsed by
+  # Dash::Commands::Proxy::State, same as the per-host proxy's.
+  def inspect_state
+    docker :inspect, container_name, "--format", Dash::Commands::Proxy::STATE_FORMAT
+  end
+
   def container_id(only_running: false)
     container_id_for(container_name: container_name, only_running: only_running)
   end
@@ -163,6 +191,32 @@ class Dash::Commands::Loadbalancer < Dash::Commands::Base
   end
 
   private
+    # Stage 3c. 3d deletes both of these with the rest of the bridge.
+    def legacy_rename_marker
+      File.join loadbalancer_config.directory, Dash::Configuration::Proxy::LEGACY_RENAME_MARKER
+    end
+
+    # Verified on the volume existing, not on a container being gone - the loadbalancer
+    # replaces no legacy container, so this is the only signal its bridge has. That makes
+    # it foolable in one specific way: if `dash-loadbalancer-config` comes to exist before
+    # this bridge ever runs on a host, the marker is written despite the legacy volume's
+    # routing table and ACME cache never having been copied. The fix is upstream of the
+    # heuristic rather than in it - every path that can create the container, and with it
+    # the volume `docker run --volume` auto-creates empty, runs the bridge first:
+    # `boot`, both reboots (Dash::Cli::Proxy::Reboot, Dash::Cli::Proxy::LoadbalancerReboot)
+    # and `dash proxy loadbalancer start` (zoolutions/dash#168).
+    #
+    # If a host is somehow in that state anyway - an operator's own `docker run`, a
+    # volume created by hand - recovery is to copy the legacy volume's contents over,
+    # then remove .legacy-renamed under this host's loadbalancer directory so this
+    # re-evaluates.
+    def mark_legacy_renamed
+      combine \
+        group(any(volume_exists(config_volume_name), negate(volume_exists(legacy_config_volume_name)))),
+        make_directory(loadbalancer_config.directory),
+        [ :touch, legacy_rename_marker ]
+    end
+
     def run_args
       loadbalancer_config.run_args
     end

data/lib/dash/commands/proxy/state.rb

@@ -0,0 +1,31 @@
+# What one `docker inspect` of a proxy container tells a boot: whether it exists, which
+# image tag it runs, and the config digest it was booted with. Three questions that used
+# to cost three round trips each (`container_id`, `version`, `config_digest`).
+#
+# Produced by Dash::Commands::Proxy#inspect_state and its loadbalancer twin, both of which
+# are captured with raise_on_non_zero_exit: false - a host with no container inspects to
+# empty output, which parses to a state that simply does not exist.
+class Dash::Commands::Proxy::State
+  attr_reader :id, :image, :digest
+
+  def self.parse(output)
+    id, image, digest = output.to_s.strip.split(" ", 3)
+    new(id: id, image: image, digest: digest)
+  end
+
+  def initialize(id: nil, image: nil, digest: nil)
+    @id = id.presence
+    @image = image.presence
+    @digest = digest.presence
+  end
+
+  def exists?
+    id.present?
+  end
+
+  # The tag, read the way Dash::Commands::Proxy#version reads it - everything past the
+  # LAST colon, so a registry host carrying a port does not get mistaken for the version.
+  def version
+    image&.split(":")&.last
+  end
+end

data/lib/dash/commands/proxy.rb

@@ -12,8 +12,13 @@ class Dash::Commands::Proxy < Dash::Commands::Base
   # 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 }}'"
+  CONFIG_DIGEST_TEMPLATE = "{{ with index .Config.Labels \"#{CONFIG_DIGEST_LABEL}\" }}{{ . }}" \
+    "{{ else }}{{ index .Config.Labels \"#{LEGACY_CONFIG_DIGEST_LABEL}\" }}{{ end }}"
+
+  CONFIG_DIGEST_FORMAT = "'#{CONFIG_DIGEST_TEMPLATE}'"
+
+  # Everything Dash::Cli::Proxy::Drift and the minimum-version gate need, in one format.
+  STATE_FORMAT = "'{{.Id}} {{.Config.Image}} #{CONFIG_DIGEST_TEMPLATE}'"
 
   def initialize(config, host:)
     super(config)
@@ -42,6 +47,41 @@ class Dash::Commands::Proxy < Dash::Commands::Base
   # destination not existing, so a second deploy is a no-op. Stage 3d deletes
   # them along with the legacy constants they read.
 
+  # Everything a proxy host needs before anything reads its container, volume or
+  # network, in the one round trip it already pays for the apps-config directory.
+  #
+  # `a || b && c` is `(a || b) && c`, so the mkdir runs whichever way the guard went -
+  # and the guard has to be the first word rather than a parenthesised group, because
+  # SSHKit prefixes the first word with /usr/bin/env and passes only `test` through.
+  # Stage 3d drops the legacy_rename half and leaves the mkdir.
+  def prepare_boot
+    combine legacy_rename, ensure_apps_config_directory
+  end
+
+  # The whole stage-3c bridge as one command, skipped outright by a host that has
+  # already been through it - or was installed fresh on 4.x and never had a kamal-proxy.
+  # The three steps keep their own bodies and their documented order (see
+  # Dash::Cli::Proxy::LegacyRename); each is wrapped in its own subshell because they
+  # all mix && and || at one precedence level, and composing them flat would
+  # re-associate across the volume copy's guard - the chain 4.0.0 got wrong.
+  #
+  # The marker is written on verified absence of both legacy containers, never on the
+  # chain's exit status: the two removals end in `|| true`, so a host whose stop failed
+  # would otherwise record itself as migrated and never retry. Its own `|| true` keeps
+  # that failure as quiet as it is today, while a failed volume copy still exits
+  # non-zero through the && chain and aborts the boot exactly as it does now.
+  def legacy_rename
+    any \
+      [ :test, "-f", legacy_rename_marker ],
+      group(
+        group(docker_commands.connect_legacy_network_containers),
+        group(copy_legacy_config_volume),
+        group(remove_legacy_container(timeout: config.drain_timeout)),
+        group(remove_legacy_holder_container),
+        group(any(mark_legacy_renamed, [ :true ]))
+      )
+  end
+
   # 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
@@ -61,6 +101,16 @@ class Dash::Commands::Proxy < Dash::Commands::Base
   # first deploy. The subshell groups create-and-copy because `&&` and `||`
   # share precedence and associate left — without it a host that already has
   # the new volume would still run the copy over live state.
+  #
+  # The source volume is still mounted by the legacy container while this runs -
+  # deliberately, on every path (see Dash::Cli::Proxy::LegacyRename's step order), and
+  # safe because every writer into it renames into place: the routing table through
+  # writeFileAtomic, the dynamic domain and redirect state through their own temp +
+  # rename, the response cache through CreateTemp + Rename, and the ACME cache through
+  # autocert.DirCache. `cp -a` reads a complete file either way. Skew across files is
+  # possible and harmless - an unused certificate, or a route whose certificate reissues -
+  # and --recheck-targets-on-restore re-verifies the targets on the way back up
+  # (zoolutions/dash#169 review).
   def copy_legacy_config_volume(volume: Dash::Configuration::Proxy::CONFIG_VOLUME, legacy: Dash::Configuration::Proxy::LEGACY_CONFIG_VOLUME)
     copy_legacy_volume(legacy: legacy, volume: volume, image: proxy_image)
   end
@@ -116,6 +166,13 @@ class Dash::Commands::Proxy < Dash::Commands::Base
     docker :inspect, container_name, "--format", CONFIG_DIGEST_FORMAT
   end
 
+  # One read for container id, image tag and config digest - parsed by
+  # Dash::Commands::Proxy::State. Capture it with raise_on_non_zero_exit: false;
+  # a host with no proxy container inspects to nothing, which is an answer.
+  def inspect_state
+    docker :inspect, container_name, "--format", STATE_FORMAT
+  end
+
   def container_id(only_running: false)
     container_id_for(container_name: container_name, only_running: only_running)
   end
@@ -327,6 +384,21 @@ class Dash::Commands::Proxy < Dash::Commands::Base
       docker :container, :inspect, name, ">", "/dev/null", "2>&1"
     end
 
+    # Stage 3c. 3d deletes both of these with the rest of the bridge.
+    def legacy_rename_marker
+      File.join config.proxy_boot.host_directory, Dash::Configuration::Proxy::LEGACY_RENAME_MARKER
+    end
+
+    # confirmed_empty?, not a negated inspect: a docker error while checking must never
+    # read as "confirmed gone" (zoolutions/dash#167 review).
+    def mark_legacy_renamed
+      combine \
+        confirmed_empty?(container_id_for(container_name: Dash::Configuration::Proxy::LEGACY_CONTAINER_NAME)),
+        confirmed_empty?(container_id_for(container_name: Dash::Configuration::Proxy::LEGACY_HOLDER_CONTAINER_NAME)),
+        make_directory(config.proxy_boot.host_directory),
+        [ :touch, legacy_rename_marker ]
+    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

data/lib/dash/commands/registry.rb

@@ -13,6 +13,20 @@ class Dash::Commands::Registry < Dash::Commands::Base
       "-p", sensitive(Dash::Utils.escape_shell_value(registry_config.password))
   end
 
+  # The login and whatever has to happen after it on the same host, in one round trip.
+  # `docker login` prints "Login Succeeded" to stdout, so its output is redirected away:
+  # a caller that captures this gets the folded command's answer and nothing else. A local
+  # registry needs no login at all, and the fold collapses to the commands alone.
+  #
+  # The credentials stay wrapped in sensitive(...) - composing keeps the array elements
+  # intact, so SSHKit redacts them here exactly as it does for a standalone login.
+  def login_then(*commands, registry_config: nil)
+    login = login(registry_config: registry_config)
+    login = [ *login, ">", "/dev/null" ] if login
+
+    combine login, *commands
+  end
+
   def logout(registry_config: nil)
     registry_config ||= config.registry
 

data/lib/dash/configuration/docs/configuration.yml

@@ -229,6 +229,12 @@ logging:
 output:
   ...
 
+# Deploy report
+#
+# Advice printed under the deploy timing table, see dash docs report:
+report:
+  ...
+
 # Aliases
 #
 # Alias configuration, see dash docs alias: