odysseus-core 0.3.2 → 0.9.0

data/lib/odysseus/deployer/ssh.rb

@@ -22,24 +22,56 @@ module Odysseus
         @session = nil
       end
 
+      # The user this connection authenticates as. Read by HostPaths, which
+      # puts host state under /var/lib for root and under $HOME for anyone
+      # else.
+      attr_reader :user
+
+      # Host and port a caller needs to open an equivalent second connection
+      # (Setup::Preparer's self-test, which must reconnect as a different
+      # user against the same target) without this class exposing @keys or
+      # @use_tailscale too -- those the caller already has, from config and
+      # from its own reasons for choosing them.
+      attr_reader :host, :port
+
       # Execute remote command
+      #
+      # Standard error is kept out of the returned value so callers can parse
+      # stdout (JSON, container IDs, inspect templates) without warning text
+      # leaking in.
+      #
+      # Commands that are expected to fail should guard themselves at the shell
+      # level (`cmd || echo 'none'`) as the Docker client's predicates do.
+      #
       # @param command [String] command to execute
-      # @return [String] command output
-      # @raise [Odysseus::SSHError] if command fails
+      # @return [String] command stdout
+      # @raise [Odysseus::SSHCommandError] if the command exits non-zero
       def execute(command)
-        puts "  > #{command}" if @verbose
+        # Redacted on the way to the terminal only; the command executed
+        # below is the real one. See Odysseus::CommandRedaction for why this
+        # lives here rather than in the CLI's own redactor.
+        puts "  > #{Odysseus::CommandRedaction.redact(command)}" if @verbose
         with_connection do |session|
-          output = ""
+          stdout = ''
+          stderr = ''
+          exit_status = nil
+
           session.open_channel do |channel|
-            channel.exec(command) do |ch, success|
+            channel.exec(command) do |_ch, success|
               raise Odysseus::SSHCommandError, "Failed to execute: #{command}" unless success
 
-              channel.on_data { |_, data| output += data }
-              channel.on_extended_data { |_, _, data| output += data }
+              channel.on_data { |_, data| stdout += data }
+              channel.on_extended_data { |_, _, data| stderr += data }
+              channel.on_request('exit-status') { |_, data| exit_status = data.read_long }
             end
           end
           session.loop
-          output
+
+          unless exit_status.nil? || exit_status.zero?
+            raise Odysseus::SSHCommandError, command_failure_message(command, exit_status, stderr, stdout)
+          end
+
+          stdout
         end
       end
 
@@ -62,11 +94,16 @@ module Odysseus
       end
 
       # Upload string content to remote file
+      #
+      # The mode travels in the SCP protocol itself, so a file holding secrets
+      # is never briefly world-readable the way a write-then-chmod would be.
+      #
       # @param content [String] content to write
       # @param remote_path [String] remote file path
-      def upload_string(content, remote_path)
+      # @param mode [Integer] permissions for the remote file
+      def upload_string(content, remote_path, mode: 0o640)
         with_connection do |session|
-          session.scp.upload!(StringIO.new(content), remote_path)
+          session.scp.upload!(StringIO.new(content), remote_path, mode: mode)
         end
       end
 
@@ -76,7 +113,7 @@ module Odysseus
       def stream(command, &block)
         with_connection do |session|
           session.open_channel do |channel|
-            channel.exec(command) do |ch, success|
+            channel.exec(command) do |_ch, success|
               raise Odysseus::SSHCommandError, "Failed to execute: #{command}" unless success
 
               channel.on_data do |_, data|
@@ -105,16 +142,34 @@ module Odysseus
 
       private
 
+      # Build a diagnostic message for a failed remote command.
+      # Prefers stderr, falls back to stdout when the command only wrote there.
+      def command_failure_message(command, exit_status, stderr, stdout)
+        details = stderr.strip
+        details = stdout.strip if details.empty?
+
+        message = "Command failed on #{@host} with exit status #{exit_status}: #{command}"
+        message += "\n#{details}" unless details.empty?
+        message
+      end
+
       def with_connection
         connect unless connected?
+        # Set only once the session is open, so the rescue below can tell a
+        # command that died from a connection that never carried one. Ruby
+        # leaves it nil when connect raises first, which is exactly the
+        # distinction needed.
+        open = true
         yield(@session)
-      rescue Errno::ECONNREFUSED => e
-        raise Odysseus::SSHConnectionError, "Connection refused to #{@host}. Is the server running and accepting SSH connections?"
-      rescue SocketError => e
+      rescue Errno::ECONNREFUSED
+        raise Odysseus::SSHConnectionError,
+              "Connection refused to #{@host}. Is the server running and accepting SSH connections?"
+      rescue SocketError
         raise Odysseus::SSHConnectionError, "Could not resolve hostname '#{@host}'. Check your DNS or /etc/hosts."
-      rescue Net::SSH::AuthenticationFailed => e
-        raise Odysseus::SSHConnectionError, "SSH authentication failed for #{@user}@#{@host}. Check your SSH keys."
-      rescue Errno::ETIMEDOUT, Net::SSH::ConnectionTimeout, Errno::EHOSTUNREACH => e
+      rescue Net::SSH::AuthenticationFailed
+        raise Odysseus::SSHAuthenticationError,
+              "SSH authentication failed for #{@user}@#{@host}. Check your SSH keys."
+      rescue Errno::ETIMEDOUT, Net::SSH::ConnectionTimeout, Errno::EHOSTUNREACH
         error_msg = "Connection to #{@host} timed out."
         if @use_tailscale
           error_msg += "\n\nThis looks like a Tailscale hostname. Please check:\n"
@@ -123,6 +178,25 @@ module Odysseus
           error_msg += "  3. The host is online: tailscale ping #{@host}"
         end
         raise Odysseus::SSHConnectionError, error_msg
+      rescue IOError, Net::SSH::Disconnect, Errno::ECONNRESET, Errno::EPIPE => e
+        # These four arrive from both directions and mean opposite things.
+        # Mid-command, the host took the work and then vanished. While
+        # opening, it accepted the TCP connection and hung up before a command
+        # existed -- a machine still booting, an sshd not up, or a name
+        # pointing at a host that is no longer there. Saying "dropped
+        # mid-command" for the second is a false claim about what happened,
+        # and it points the reader at a flaky network instead of a host that
+        # never answered.
+        raise Odysseus::SSHConnectionError, drop_message(open, e)
+      end
+
+      # @param open [Boolean, nil] whether the session was established
+      def drop_message(open, error)
+        return "Connection to #{@host} dropped mid-command rather than failing to open: #{error.message}" if open
+
+        "#{@host} accepted the connection and then closed it before any command ran: #{error.message}. " \
+          'The host may still be booting, sshd may not be running yet, or the name may point at a ' \
+          'machine that is no longer there.'
       end
 
       def connect
@@ -131,7 +205,7 @@ module Odysseus
           port: @port,
           non_interactive: true,
           verify_host_key: :never,
-          timeout: 10  # Connection timeout in seconds
+          timeout: 10 # Connection timeout in seconds
         }
         options[:keys] = @keys if @keys.any?
 

data/lib/odysseus/docker/client.rb

@@ -1,12 +1,13 @@
 # lib/odysseus/docker/client.rb
 
 require 'json'
+require 'securerandom'
+require 'shellwords'
 
 module Odysseus
   module Docker
     class Client
       HEALTHCHECK_POLL_INTERVAL = 2 # seconds
-      HEALTHCHECK_MAX_ATTEMPTS = 30 # ~60 seconds max wait
 
       # @param ssh [Odysseus::Deployer::SSH] SSH connection to server
       def initialize(ssh)
@@ -14,23 +15,33 @@ module Odysseus
       end
 
       # Run a new container
+      #
+      # Environment variables travel in a 0600 env file rather than on the
+      # command line, so secrets stay out of the host's process list and values
+      # containing spaces or shell metacharacters survive intact. Docker copies
+      # them into the container config at create time, so the file is removed
+      # again as soon as the container exists.
+      #
       # @param name [String] container name
       # @param image [String] image:tag
       # @param options [Hash] container options
       # @return [String] container ID
       def run(name:, image:, options: {})
-        cmd = build_run_command(name: name, image: image, options: options)
+        env_file = env_file_path(name, options[:env])
+        write_env_file(env_file, options[:env])
+
+        cmd = build_run_command(name: name, image: image, options: options, env_file: env_file)
         output = @ssh.execute(cmd)
         # Container ID is the last line (64-char hex), ignore any warnings
         lines = output.strip.split("\n")
         container_id = lines.last&.strip
 
         # Validate it looks like a container ID
-        unless container_id&.match?(/\A[a-f0-9]{64}\z/)
-          raise Odysseus::DeployError, "Failed to start container: #{output}"
-        end
+        raise Odysseus::DeployError, "Failed to start container: #{output}" unless container_id&.match?(/\A[a-f0-9]{64}\z/)
 
         container_id
+      ensure
+        remove_env_file(env_file)
       end
 
       # Stop a container
@@ -77,7 +88,7 @@ module Odysseus
       # @param timeout [Integer] max seconds to wait
       # @return [Boolean] true if healthy, false if timeout
       def wait_healthy(container_id, timeout: 60)
-        attempts = [timeout / HEALTHCHECK_POLL_INTERVAL, HEALTHCHECK_MAX_ATTEMPTS].min
+        attempts = [timeout / HEALTHCHECK_POLL_INTERVAL, 1].max
 
         attempts.times do
           status = health_status(container_id)
@@ -100,6 +111,16 @@ module Odysseus
         output.strip == 'true'
       end
 
+      # Check if a container exists, running or stopped
+      # @param container_id [String] container ID or name
+      # @return [Boolean]
+      def container_exists?(container_id)
+        output = @ssh.execute(
+          "docker inspect --format '{{.Id}}' #{container_id} 2>/dev/null || echo ''"
+        )
+        !output.strip.empty?
+      end
+
       # Get container IP address
       # @param container_id [String] container ID or name
       # @param network [String] network name (default: bridge)
@@ -126,6 +147,50 @@ module Odysseus
         !output.strip.empty?
       end
 
+      # Tags of the images present locally for a repository.
+      #
+      # docker orders these newest-created first, which is the fallback
+      # ordering a rollback uses on a host with no deploy log. Untagged
+      # (dangling) images report a tag of '<none>' and are dropped: they cannot
+      # be named in a docker run, so they are never rollback targets.
+      #
+      # @param image [String] repository name, without a tag
+      # @return [Array<String>] tags present on this host
+      def image_tags(image)
+        output = @ssh.execute(
+          "docker images #{Shellwords.escape(image)} --format '{{.Tag}}' 2>/dev/null || true"
+        )
+
+        output.lines.map(&:strip).reject { |tag| tag.empty? || tag == '<none>' }
+      end
+
+      # Remove one image by reference.
+      #
+      # Lets SSHCommandError through deliberately: docker refuses to remove an
+      # image a container still references, and the caller prunes one image at a
+      # time so a refusal is a logged skip rather than a failed deploy.
+      #
+      # @param image [String] repository:tag
+      # @return [String] docker's output
+      def remove_image(image)
+        @ssh.execute("docker image rm #{Shellwords.escape(image)}")
+      end
+
+      # The versions any container on this host still references.
+      #
+      # Includes stopped containers (`all: true`): a stopped container still
+      # references its image, whether it stopped from a crash, a reboot, or by
+      # hand, and deleting that image would remove something an operator may
+      # still need. Used to protect those versions from retention.
+      #
+      # @param service_labels [Array<String>] odysseus.service values to check
+      # @return [Array<String>] distinct odysseus.version labels found
+      def versions_in_use(service_labels)
+        service_labels.flat_map { |label| list(service: label, all: true) }
+                      .filter_map { |container| Odysseus::Docker::Labels.version_of(container) }
+                      .uniq
+      end
+
       # Get logs from a container
       # @param container_id [String] container ID or name
       # @param follow [Boolean] follow log output (streaming)
@@ -133,7 +198,7 @@ module Odysseus
       # @param since [String] show logs since timestamp (e.g., '10m', '2h', '2024-01-01')
       # @param timestamps [Boolean] show timestamps
       # @return [String] log output (or yields lines if block given)
-      def logs(container_id, follow: false, tail: 100, since: nil, timestamps: false, &block)
+      def logs(container_id, follow: false, tail: 100, since: nil, timestamps: false, &)
         parts = ['docker logs']
         parts << '--follow' if follow
         parts << "--tail #{tail}" if tail
@@ -144,7 +209,7 @@ module Odysseus
         cmd = parts.join(' ')
 
         if block_given?
-          @ssh.stream(cmd, &block)
+          @ssh.stream(cmd, &)
         else
           @ssh.execute(cmd)
         end
@@ -167,32 +232,63 @@ module Odysseus
       end
 
       # Run a one-off command in a new container (doesn't persist)
+      #
+      # The environment travels in a 0600 env file, exactly as a deployed
+      # container's does: `rails db:migrate` needs the app's DATABASE_URL, and
+      # putting it on the command line would show it in the host's process list
+      # and break any value containing a space.
+      #
       # @param image [String] image to use
-      # @param command [String] command to execute
+      # @param command [String] command to execute, as a shell command line
       # @param options [Hash] container options (env, volumes, network, etc.)
       # @return [String] command output
       def run_once(image:, command:, options: {})
-        parts = ['docker run --rm']
+        with_env_file(options[:env]) do |env_file|
+          parts = ['docker run --rm']
 
-        # Environment variables
-        options[:env]&.each do |key, value|
-          parts << "-e #{key}=#{value}"
-        end
+          # Environment variables (see #write_env_file — never inlined here)
+          parts << "--env-file #{Shellwords.escape(env_file)}" if env_file
 
-        # Volume mounts
-        options[:volumes]&.each { |v| parts << "-v #{v}" }
+          # Volume mounts
+          options[:volumes]&.each { |v| parts << "-v #{v}" }
 
-        # Network
-        parts << "--network #{options[:network]}" if options[:network]
+          # Network
+          parts << "--network #{options[:network]}" if options[:network]
 
-        # Interactive/TTY
-        parts << '-i' if options[:interactive]
-        parts << '-t' if options[:tty]
+          # Interactive/TTY
+          parts << '-i' if options[:interactive]
+          parts << '-t' if options[:tty]
 
-        parts << image
-        parts << command
+          parts << Shellwords.escape(image)
+          # Not escaped: the command is a command line, and `rake db:migrate`
+          # has to reach docker as two arguments. build_run_command treats
+          # options[:cmd] the same way.
+          parts << command
 
-        @ssh.execute(parts.join(' '))
+          @ssh.execute(parts.join(' '))
+        end
+      end
+
+      # Hold an env file open on the host for the duration of a block.
+      #
+      # For runs Odysseus does not execute itself: `app shell` and `app console`
+      # need an interactive TTY, so the CLI builds its own `ssh -t ... docker
+      # run` and passes the yielded path as --env-file. The file goes away
+      # afterwards whether the block returned or raised, and remove_env_file
+      # never masks the block's own failure.
+      #
+      # Yields nil, having written nothing, when there is no environment, so
+      # the caller has one code path either way.
+      #
+      # @param env [Hash, nil] environment variables
+      # @yieldparam path [String, nil] path to the env file on the host
+      # @return [Object] whatever the block returned
+      def with_env_file(env)
+        path = env_file_path(one_off_env_name, env)
+        write_env_file(path, env)
+        yield path
+      ensure
+        remove_env_file(path)
       end
 
       # Cleanup old stopped containers, keeping only the last N
@@ -278,35 +374,121 @@ module Odysseus
 
       private
 
-      def build_run_command(name:, image:, options:)
+      # Where this connection's env files go. Derived rather than constant
+      # because a deploy user cannot write — or chmod — the system directory.
+      def host_paths
+        @host_paths ||= Odysseus::HostPaths.new(@ssh)
+      end
+
+      # Where a container's env file goes, or nil when there is nothing to
+      # write. Settled before the write rather than returned by it: scp creates
+      # the remote file and then streams into it, so an upload that dies partway
+      # has already left part of a file of secrets on the host, and a caller
+      # that learned the path from the write's return value has nothing to
+      # remove — the file stays under a name nobody is going to look for.
+      #
+      # @return [String, nil] path to the env file, nil when there is nothing to write
+      def env_file_path(name, env)
+        return nil if env.nil? || env.empty?
+
+        "#{host_paths.env_dir}/#{name}.env"
+      end
+
+      # Write the container's environment to a private file on the host.
+      #
+      # The directory is made 0700 before anything is written into it. The file
+      # itself is uploaded 0600, so this is a second guard rather than the only
+      # one — but it is the guard that has to hold for a file left behind by a
+      # session that died, and `mkdir -p` on its own leaves the directory 0755.
+      def write_env_file(path, env)
+        return unless path
+
+        dir = host_paths.env_dir
+        @ssh.execute("mkdir -p #{Shellwords.escape(dir)} && chmod 700 #{Shellwords.escape(dir)}")
+        @ssh.upload_string(format_env_file(env), path, mode: 0o600)
+      end
+
+      # The name a one-off run's env file is written under.
+      #
+      # write_env_file names the file after the container, and a one-off has no
+      # container name. '@' is not a character Docker allows in one
+      # ([a-zA-Z0-9][a-zA-Z0-9_.-]*), so no deployed container's env file can
+      # ever live at this path — overwriting a running container's env file, or
+      # deleting it on the way out, would be a live incident. The random suffix
+      # keeps two one-off runs on the same host from sharing a file.
+      def one_off_env_name
+        "one-off@#{SecureRandom.hex(8)}"
+      end
+
+      # docker --env-file takes one KEY=VALUE per line and cannot represent a
+      # value containing a newline, so refuse rather than truncate a secret.
+      def format_env_file(env)
+        lines = env.map do |key, value|
+          value = value.to_s
+          if value.include?("\n")
+            raise Odysseus::DeployError,
+                  "Environment variable #{key} contains a newline, which a Docker env file cannot represent"
+          end
+
+          "#{key}=#{value}"
+        end
+
+        "#{lines.join("\n")}\n"
+      end
+
+      # Remove the env file, reconnecting once if the connection it was written
+      # over has died in the meantime.
+      #
+      # This runs from an ensure, and on the interactive paths the connection
+      # has been held open — idle, and with nothing pumping it — for as long as
+      # the user's session lasted. An idle NAT or firewall timeout, sshd's
+      # ClientAlive limit or a Tailscale relay change all leave it dead by the
+      # time the session ends, and a dead connection raises IOError,
+      # Net::SSH::Disconnect, Errno::EPIPE or Errno::ECONNRESET — none of them
+      # an Odysseus::SSHError, which is all this used to rescue. The cleanup's
+      # own failure then escaped the ensure and replaced whatever the block was
+      # already raising, so `app shell`'s exit status arrived as a backtrace.
+      #
+      # Closing the session is what makes the second attempt a new one: SSH
+      # connects lazily and only when it has no live session. If that fails too
+      # the file is left behind — 0600 in a 0700 directory — and nothing is
+      # raised: the caller came for the block's outcome, not this one's.
+      def remove_env_file(path)
+        return unless path
+
+        @ssh.execute("rm -f #{Shellwords.escape(path)}")
+      rescue StandardError
+        remove_env_file_on_a_new_connection(path)
+      end
+
+      def remove_env_file_on_a_new_connection(path)
+        @ssh.close
+        @ssh.execute("rm -f #{Shellwords.escape(path)}")
+      rescue StandardError
+        nil
+      end
+
+      def build_run_command(name:, image:, options:, env_file: nil)
         parts = ['docker run -d']
 
         # Container name
         parts << "--name #{name}"
 
-        # Labels for tracking
-        parts << "--label odysseus.service=#{options[:service] || name}"
-        parts << "--label odysseus.version=#{options[:version]}" if options[:version]
+        # Labels for tracking. Values are quoted: they carry refs and timestamps
+        # supplied by the app's repository, not just internal identifiers.
+        parts << "--label #{Shellwords.escape("odysseus.service=#{options[:service] || name}")}"
+        parts << "--label #{Shellwords.escape("odysseus.version=#{options[:version]}")}" if options[:version]
 
         # Additional custom labels
-        if options[:labels]
-          options[:labels].each do |key, value|
-            parts << "--label #{key}=#{value}"
-          end
+        options[:labels]&.each do |key, value|
+          parts << "--label #{Shellwords.escape("#{key}=#{value}")}"
         end
 
         # Port mappings
-        if options[:ports]
-          options[:ports].each { |p| parts << "-p #{p}" }
-        end
+        options[:ports]&.each { |p| parts << "-p #{p}" }
 
-        # Environment variables
-        if options[:env]
-          options[:env].each do |key, value|
-            # Don't log secret values
-            parts << "-e #{key}=#{value}"
-          end
-        end
+        # Environment variables (see #write_env_file — never inlined here)
+        parts << "--env-file #{Shellwords.escape(env_file)}" if env_file
 
         # Memory limits
         parts << "--memory #{options[:memory]}" if options[:memory]
@@ -319,7 +501,15 @@ module Odysseus
         # Health check (use image's HEALTHCHECK by default)
         if options[:healthcheck]
           hc = options[:healthcheck]
-          parts << "--health-cmd '#{hc[:cmd]}'" if hc[:cmd]
+          # Escaped, not hand-quoted. A cmd containing a single quote --
+          # `--execute='SELECT 1'`, which is how you write a one-shot query
+          # for most database clients -- closed the quote early, and the
+          # remainder word-split into docker's argument list: the tail landed
+          # where the image name goes, and docker reported it could not find
+          # the image '1:latest'. Shellwords makes it one word whatever it
+          # contains; docker runs it through a shell at the other end, so the
+          # inner quoting still means what it says.
+          parts << "--health-cmd #{Shellwords.escape(hc[:cmd])}" if hc[:cmd]
           parts << "--health-interval #{hc[:interval]}s" if hc[:interval]
           parts << "--health-timeout #{hc[:timeout]}s" if hc[:timeout]
           parts << "--health-retries #{hc[:retries]}" if hc[:retries]
@@ -328,10 +518,9 @@ module Odysseus
         # Network
         parts << "--network #{options[:network]}" if options[:network]
 
-        # Volume mounts
-        if options[:volumes]
-          options[:volumes].each { |v| parts << "-v #{v}" }
-        end
+        # Volume mounts. Escaped for the same reason as the healthcheck above:
+        # a host path with a space in it is otherwise two arguments.
+        options[:volumes]&.each { |v| parts << "-v #{Shellwords.escape(v)}" }
 
         # Restart policy
         parts << "--restart #{options[:restart] || 'unless-stopped'}"
@@ -339,7 +528,10 @@ module Odysseus
         # Image
         parts << image
 
-        # Command (if provided)
+        # Command (if provided). Deliberately NOT escaped, unlike everything
+        # above: `start-single-node --insecure` has to reach the container as
+        # three arguments, and escaping it would hand docker one literal
+        # string containing spaces. Do not "fix" this to match its neighbours.
         parts << options[:cmd] if options[:cmd]
 
         parts.join(' ')

data/lib/odysseus/docker/labels.rb

@@ -0,0 +1,43 @@
+# lib/odysseus/docker/labels.rb
+
+module Odysseus
+  module Docker
+    # docker ps --format '{{json .}}' reports labels as one flat string:
+    # "k=v,k2=v2". This turns that back into a hash.
+    module Labels
+      VERSION_KEY = 'odysseus.version'.freeze
+
+      # @param raw [String, nil] the Labels field of a docker ps entry
+      # @return [Hash{String => String}]
+      def self.parse(raw)
+        return {} if raw.nil? || raw.empty?
+
+        raw.split(',').each_with_object({}) do |pair, acc|
+          key, value = pair.split('=', 2)
+          acc[key] = value.to_s unless key.nil? || key.empty?
+        end
+      end
+
+      # @param container [Hash] a docker ps entry
+      # @return [String, nil] the deployed version, when labelled
+      def self.version_of(container)
+        parse(container['Labels'])[VERSION_KEY]
+      end
+
+      # The odysseus.service label value carried by a role's containers.
+      #
+      # WebDeploy labels the web role with the bare service name; JobDeploy
+      # labels every other role "<service>-<role>". Both conventions predate
+      # this method, which exists so that reading containers back cannot
+      # disagree with writing them. docker ps filters on an exact label match,
+      # so a wrong value here silently reports nothing running.
+      #
+      # @param service [String] the service name from deploy.yml
+      # @param role [Symbol, String] the server role
+      # @return [String]
+      def self.service_for(service:, role:)
+        role.to_sym == :web ? service.to_s : "#{service}-#{role}"
+      end
+    end
+  end
+end

data/lib/odysseus/errors.rb

@@ -9,10 +9,18 @@ module Odysseus
   class ConfigMissingKeyError < ConfigError; end
 
   class DeployError < Error; end
+  class RollbackError < DeployError; end
   class SSHError < DeployError; end
   class SSHConnectionError < SSHError; end
+  # Distinct from SSHConnectionError: the host was reached and refused
+  # this identity. Only a caller that knows which identities are
+  # available can advise on that, so it needs to be catchable on its own.
+  class SSHAuthenticationError < SSHError; end
   class SSHCommandError < SSHError; end
 
+  class ProxyError < Error; end
+  class ProxyApiError < ProxyError; end
+
   class RegistryError < Error; end
   class RegistryPushError < RegistryError; end
   class RegistryAuthError < RegistryError; end
@@ -24,4 +32,6 @@ module Odysseus
   class GeneratorError < Error; end
   class DockerComposeGenerationError < GeneratorError; end
   class CaddyGenerationError < GeneratorError; end
+
+  class SetupError < Error; end
 end