dash 2.12.0

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

@@ -0,0 +1,54 @@
+# Roles
+#
+# Roles are used to configure different types of servers in the deployment.
+# The most common use for this is to run web servers and job servers.
+#
+# Kamal expects there to be a `web` role, unless you set a different `primary_role`
+# in the root configuration.
+
+# Role configuration
+#
+# Roles are specified under the servers key:
+servers:
+
+  # Simple role configuration
+  #
+  # This can be a list of hosts if you don't need custom configuration for the role.
+  #
+  # You can set tags on the hosts for custom env variables (see kamal docs env):
+  web:
+    - 172.1.0.1
+    - 172.1.0.2: experiment1
+    - 172.1.0.2: [ experiment1, experiment2 ]
+
+  # Custom role configuration
+  #
+  # When there are other options to set, the list of hosts goes under the `hosts` key.
+  #
+  # By default, only the primary role uses a proxy.
+  #
+  # For other roles, you can set it to `proxy: true` to enable it and inherit the root proxy
+  # configuration or provide a map of options to override the root configuration.
+  #
+  # For the primary role, you can set `proxy: false` to disable the proxy.
+  #
+  # You can also set a custom `cmd` to run in the container and overwrite other settings
+  # from the root configuration.
+  workers:
+    hosts:
+      - 172.1.0.3
+      - 172.1.0.4: experiment1
+    cmd: "bin/jobs"
+    stop_timeout: 30
+    options:
+      memory: 2g
+      cpus: 4
+    logging:
+      ...
+    proxy:
+      ...
+    labels:
+      my-label: workers
+    env:
+      ...
+    asset_path: /public

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

@@ -0,0 +1,27 @@
+# Servers
+#
+# Servers are split into different roles, with each role having its own configuration.
+#
+# For simpler deployments, though, where all servers are identical, you can just specify a list of servers.
+# They will be implicitly assigned to the `web` role.
+servers:
+  - 172.0.0.1
+  - 172.0.0.2
+  - 172.0.0.3
+
+# Tagging servers
+#
+# Servers can be tagged, with the tags used to add custom env variables (see kamal docs env).
+servers:
+  - 172.0.0.1
+  - 172.0.0.2: experiments
+  - 172.0.0.3: [ experiments, three ]
+
+# Roles
+#
+# For more complex deployments (e.g., if you are running job hosts), you can specify roles and configure each separately (see kamal docs role):
+servers:
+  web:
+    ...
+  workers:
+    ...

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

@@ -0,0 +1,81 @@
+# SSH configuration
+#
+# Kamal uses SSH to connect and run commands on your hosts.
+# By default, it will attempt to connect to the root user on port 22.
+#
+# If you are using a non-root user, you may need to bootstrap your servers manually before using them with Kamal. On Ubuntu, you’d do:
+#
+# ```shell
+# sudo apt update
+# sudo apt upgrade -y
+# sudo apt install -y docker.io curl git
+# sudo usermod -a -G docker app
+# ```
+
+# SSH options
+#
+# The options are specified under the ssh key in the configuration file.
+ssh:
+
+  # The SSH user
+  #
+  # Defaults to `root`:
+  user: app
+
+  # The SSH port
+  #
+  # Defaults to 22:
+  port: "2222"
+
+  # Proxy host
+  #
+  # Specified in the form <host> or <user>@<host>:
+  proxy: root@proxy-host
+
+  # Proxy command
+  #
+  # A custom proxy command, required for older versions of SSH:
+  proxy_command: "ssh -W %h:%p user@proxy"
+
+  # Log level
+  #
+  # Defaults to `fatal`. Set this to `debug` if you are having SSH connection issues.
+  log_level: debug
+
+  # Keys only
+  #
+  # Set to `true` to use only private keys from the `keys` and `key_data` parameters,
+  # even if ssh-agent offers more identities. This option is intended for
+  # situations where ssh-agent offers many different identities or you
+  # need to overwrite all identities and force a single one.
+  keys_only: false
+
+  # Keys
+  #
+  # An array of file names of private keys to use for public key
+  # and host-based authentication:
+  keys: [ "~/.ssh/id.pem" ]
+
+  # Key data
+  #
+  # An array of strings, with each element of the array being a secret name.
+  key_data:
+    - SSH_PRIVATE_KEY
+  # You can also provide raw private key in PEM format, but this is deprecated.
+  key_data:
+    - "-----BEGIN OPENSSH PRIVATE KEY----- ..."
+
+  # Config
+  #
+  # Set to true to load the default OpenSSH config files (~/.ssh/config,
+  # /etc/ssh_config), to false ignore config files, or to a file path
+  # (or array of paths) to load specific configuration. Defaults to true.
+  config: [ "~/.ssh/myconfig" ]
+
+  # Forward agent
+  #
+  # Whether to forward the local SSH agent to the remote host. Defaults to
+  # true (sshkit's default). Set to false when connecting through a jump
+  # host or tunnel that does not support agent forwarding (for example,
+  # Cloudflare Access for Infrastructure with SSH).
+  forward_agent: false

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

@@ -0,0 +1,31 @@
+# SSHKit
+#
+# [SSHKit](https://github.com/capistrano/sshkit) is the SSH toolkit used by Kamal.
+#
+# The default, settings should be sufficient for most use cases, but
+# when connecting to a large number of hosts, you may need to adjust.
+
+# SSHKit options
+#
+# The options are specified under the sshkit key in the configuration file.
+sshkit:
+
+  # Max concurrent starts
+  #
+  # Creating SSH connections concurrently can be an issue when deploying to many servers.
+  # By default, Kamal will limit concurrent connection starts to 30 at a time.
+  max_concurrent_starts: 10
+
+  # Pool idle timeout
+  #
+  # Kamal sets a long idle timeout of 900 seconds on connections to try to avoid
+  # re-connection storms after an idle period, such as building an image or waiting for CI.
+  pool_idle_timeout: 300
+
+  # DNS retry settings
+  #
+  # Some resolvers (mDNSResponder, systemd-resolved, Tailscale) can drop lookups during
+  # bursts of concurrent SSH starts. Kamal will retry DNS failures automatically.
+  #
+  # Number of retries after the initial attempt. Set to 0 to disable.
+  dns_retries: 3

data/lib/kamal/configuration/env/tag.rb

@@ -0,0 +1,13 @@
+class Kamal::Configuration::Env::Tag
+  attr_reader :name, :config, :secrets
+
+  def initialize(name, config:, secrets:)
+    @name = name
+    @config = config
+    @secrets = secrets
+  end
+
+  def env
+    Kamal::Configuration::Env.new(config: config, secrets: secrets)
+  end
+end

data/lib/kamal/configuration/env.rb

@@ -0,0 +1,42 @@
+class Kamal::Configuration::Env
+  include Kamal::Configuration::Validation
+
+  attr_reader :context, :clear, :secrets, :secret_keys
+  delegate :argumentize, to: Kamal::Utils
+
+  def initialize(config:, secrets:, context: "env")
+    @clear = config.fetch("clear", config.key?("secret") || config.key?("tags") ? {} : config)
+    @secrets = secrets
+    @secret_keys = config.fetch("secret", [])
+    @context = context
+    validate! config, context: context, with: Kamal::Configuration::Validator::Env
+  end
+
+  def clear_args
+    argumentize("--env", clear)
+  end
+
+  def secrets_io
+    Kamal::EnvFile.new(aliased_secrets).to_io
+  end
+
+  def merge(other)
+    self.class.new \
+      config: { "clear" => clear.merge(other.clear), "secret" => secret_keys | other.secret_keys },
+      secrets: secrets
+  end
+
+  def to_h
+    clear.merge(aliased_secrets)
+  end
+
+  private
+    def aliased_secrets
+      secret_keys.to_h { |key| extract_alias(key) }.transform_values { |secret_key| secrets[secret_key] }
+    end
+
+    def extract_alias(key)
+      key_name, key_aliased_to = key.split(":", 2)
+      [ key_name, key_aliased_to || key_name ]
+    end
+end

data/lib/kamal/configuration/loadbalancer.rb

@@ -0,0 +1,34 @@
+class Kamal::Configuration::Loadbalancer < Kamal::Configuration::Proxy
+  CONTAINER_NAME = "load-balancer".freeze
+  SHARED_CONTAINER_NAME = "kamal-proxy".freeze
+
+  def self.validation_config_key
+    "proxy"
+  end
+
+  def initialize(config:, proxy_config:, secrets:)
+    super
+  end
+
+  def deploy_options
+    opts = super
+
+    opts[:host] = hosts if hosts.present?
+    opts[:tls] = proxy_config["ssl"].presence
+
+    opts
+  end
+
+  def directory
+    File.join config.run_directory, "loadbalancer"
+  end
+
+  def container_name
+    on_proxy_host? ? SHARED_CONTAINER_NAME : CONTAINER_NAME
+  end
+
+  # When loadbalancer is on a proxy host, it takes over the proxy role
+  def on_proxy_host?
+    config.proxy_hosts.include?(config.proxy.effective_loadbalancer)
+  end
+end

data/lib/kamal/configuration/logging.rb

@@ -0,0 +1,33 @@
+class Kamal::Configuration::Logging
+  delegate :optionize, :argumentize, to: Kamal::Utils
+
+  include Kamal::Configuration::Validation
+
+  attr_reader :logging_config
+
+  def initialize(logging_config:, context: "logging")
+    @logging_config = logging_config || {}
+    validate! @logging_config, context: context
+  end
+
+  def driver
+    logging_config["driver"]
+  end
+
+  def options
+    logging_config.fetch("options", {})
+  end
+
+  def merge(other)
+    self.class.new logging_config: logging_config.deep_merge(other.logging_config)
+  end
+
+  def args
+    if driver.present? || options.present?
+      optionize({ "log-driver" => driver }.compact) +
+        argumentize("--log-opt", options)
+    else
+      argumentize("--log-opt", { "max-size" => "10m" })
+    end
+  end
+end

data/lib/kamal/configuration/output.rb

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

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

@@ -0,0 +1,124 @@
+class Kamal::Configuration::Proxy::Boot
+  attr_reader :config
+  delegate :argumentize, :optionize, to: Kamal::Utils
+
+  def initialize(config:)
+    @config = config
+  end
+
+  def publish_args(http_port, https_port, bind_ips = nil)
+    ensure_valid_bind_ips(bind_ips)
+
+    (bind_ips || [ nil ]).map do |bind_ip|
+      bind_ip = format_bind_ip(bind_ip)
+      publish_http = [ bind_ip, http_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT ].compact.join(":")
+      publish_https = [ bind_ip, https_port, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT ].compact.join(":")
+
+      argumentize "--publish", [ publish_http, publish_https ]
+    end.join(" ")
+  end
+
+  def logging_args(max_size)
+    argumentize "--log-opt", "max-size=#{max_size}" if max_size.present?
+  end
+
+  def default_boot_options
+    [
+      *(publish_args(Kamal::Configuration::Proxy::Run::DEFAULT_HTTP_PORT, Kamal::Configuration::Proxy::Run::DEFAULT_HTTPS_PORT, nil)),
+      *(logging_args(Kamal::Configuration::Proxy::Run::DEFAULT_LOG_MAX_SIZE))
+    ]
+  end
+
+  def repository_name
+    "ghcr.io/mhenrixon"
+  end
+
+  def image_name
+    "kamal-proxy"
+  end
+
+  def image_default
+    "#{repository_name}/#{image_name}"
+  end
+
+  def container_name
+    "kamal-proxy"
+  end
+
+  def host_directory
+    File.join config.run_directory, "proxy"
+  end
+
+  def options_file
+    File.join host_directory, "options"
+  end
+
+  def image_file
+    File.join host_directory, "image"
+  end
+
+  def image_version_file
+    File.join host_directory, "image_version"
+  end
+
+  def run_command_file
+    File.join host_directory, "run_command"
+  end
+
+  def apps_directory
+    File.join host_directory, "apps-config"
+  end
+
+  def apps_container_directory
+    "/home/kamal-proxy/.apps-config"
+  end
+
+  def apps_volume
+    Kamal::Configuration::Volume.new \
+      host_path: apps_directory,
+      container_path: apps_container_directory
+  end
+
+  def app_directory
+    File.join apps_directory, config.service_and_destination
+  end
+
+  def app_container_directory
+    File.join apps_container_directory, config.service_and_destination
+  end
+
+  def error_pages_directory
+    File.join app_directory, "error_pages"
+  end
+
+  def error_pages_container_directory
+    File.join app_container_directory, "error_pages"
+  end
+
+  def tls_directory
+    File.join app_directory, "tls"
+  end
+
+  def tls_container_directory
+    File.join app_container_directory, "tls"
+  end
+
+  private
+    def ensure_valid_bind_ips(bind_ips)
+      bind_ips.present? && bind_ips.each do |ip|
+        next if ip =~ Resolv::IPv4::Regex || ip =~ Resolv::IPv6::Regex
+        raise ArgumentError, "Invalid publish IP address: #{ip}"
+      end
+
+      true
+    end
+
+    def format_bind_ip(ip)
+      # Ensure IPv6 address inside square brackets - e.g. [::1]
+      if ip =~ Resolv::IPv6::Regex && ip !~ /\A\[.*\]\z/
+        "[#{ip}]"
+      else
+        ip
+      end
+    end
+end

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

@@ -0,0 +1,152 @@
+class Kamal::Configuration::Proxy::Run
+  MINIMUM_VERSION = "v0.9.2.1"
+  DEFAULT_HTTP_PORT = 80
+  DEFAULT_HTTPS_PORT = 443
+  DEFAULT_LOG_MAX_SIZE = "10m"
+
+  attr_reader :config, :run_config
+  delegate :argumentize, :optionize, to: Kamal::Utils
+
+  def initialize(config, run_config:, context: "proxy/run")
+    @config = config
+    @run_config = run_config
+    @context = context
+  end
+
+  def debug?
+    run_config.fetch("debug", nil)
+  end
+
+  def publish?
+    run_config.fetch("publish", true)
+  end
+
+  def http_port
+    run_config.fetch("http_port", DEFAULT_HTTP_PORT)
+  end
+
+  def https_port
+    run_config.fetch("https_port", DEFAULT_HTTPS_PORT)
+  end
+
+  def bind_ips
+    run_config.fetch("bind_ips", nil)
+  end
+
+  def publish_args
+    if publish?
+      (bind_ips || [ nil ]).map do |bind_ip|
+        bind_ip = format_bind_ip(bind_ip)
+        publish_http = [ bind_ip, http_port, DEFAULT_HTTP_PORT ].compact.join(":")
+        publish_https = [ bind_ip, https_port, DEFAULT_HTTPS_PORT ].compact.join(":")
+
+        argumentize "--publish", [ publish_http, publish_https ]
+      end.join(" ")
+    end
+  end
+
+  def log_max_size
+    run_config.fetch("log_max_size", DEFAULT_LOG_MAX_SIZE)
+  end
+
+  def logging_args
+    argumentize "--log-opt", "max-size=#{log_max_size}" if log_max_size.present?
+  end
+
+  def version
+    run_config.fetch("version", MINIMUM_VERSION)
+  end
+
+  def registry
+    run_config.fetch("registry", nil)
+  end
+
+  def repository
+    run_config.fetch("repository", "ghcr.io/mhenrixon/kamal-proxy")
+  end
+
+  def image
+    "#{[ registry, repository ].compact.join("/")}:#{version}"
+  end
+
+  def container_name
+    "kamal-proxy"
+  end
+
+  def options_args
+    if args = run_config["options"]
+      optionize args
+    end
+  end
+
+  def run_command
+    [ "kamal-proxy", "run", *optionize(run_command_options) ].join(" ")
+  end
+
+  def metrics_port
+    run_config["metrics_port"]
+  end
+
+  def run_command_options
+    { debug: debug? || nil, "metrics-port": metrics_port }.compact
+  end
+
+  def docker_options_args
+    [
+      *apps_volume_args,
+      *publish_args,
+      *logging_args,
+      *("--expose=#{metrics_port}" if metrics_port.present?),
+      *options_args
+    ].compact
+  end
+
+  def host_directory
+    File.join config.run_directory, "proxy"
+  end
+
+  def apps_directory
+    File.join host_directory, "apps-config"
+  end
+
+  def apps_container_directory
+    "/home/kamal-proxy/.apps-config"
+  end
+
+  def apps_volume
+    Kamal::Configuration::Volume.new \
+      host_path: apps_directory,
+      container_path: apps_container_directory
+  end
+
+  def apps_volume_args
+    [ apps_volume.docker_args ]
+  end
+
+  def app_directory
+    File.join apps_directory, config.service_and_destination
+  end
+
+  def app_container_directory
+    File.join apps_container_directory, config.service_and_destination
+  end
+
+  def ==(other)
+    other.is_a?(self.class) && run_config == other.run_config
+  end
+  alias_method :eql?, :==
+
+  def hash
+    run_config.hash
+  end
+
+  private
+    def format_bind_ip(ip)
+      # Ensure IPv6 address inside square brackets - e.g. [::1]
+      if ip =~ Resolv::IPv6::Regex && ip !~ /\A\[.*\]\z/
+        "[#{ip}]"
+      else
+        ip
+      end
+    end
+end