dash 2.12.0

data/lib/kamal/configuration/builder.rb

@@ -0,0 +1,218 @@
+class Kamal::Configuration::Builder
+  include Kamal::Configuration::Validation
+
+  attr_reader :config, :builder_config
+  delegate :image, :service, to: :config
+  delegate :server, to: :"config.registry"
+
+  def initialize(config:)
+    @config = config
+    @builder_config = config.raw_config.builder || {}
+    @image = config.image
+    @server = config.registry.server
+    @service = config.service
+
+    validate! builder_config, with: Kamal::Configuration::Validator::Builder
+  end
+
+  def to_h
+    builder_config
+  end
+
+  def remote
+    builder_config["remote"]
+  end
+
+  def arches
+    Array(builder_config.fetch("arch", default_arch))
+  end
+
+  def local_arches
+    @local_arches ||= if local_disabled?
+      []
+    elsif remote
+      arches & [ Kamal::Utils.docker_arch ]
+    else
+      arches
+    end
+  end
+
+  def remote_arches
+    @remote_arches ||= if remote
+      arches - local_arches
+    else
+      []
+    end
+  end
+
+  def remote?
+    remote_arches.any?
+  end
+
+  def local?
+    !local_disabled? && (arches.empty? || local_arches.any?)
+  end
+
+  def cloud?
+    driver.start_with? "cloud"
+  end
+
+  def cached?
+    !!builder_config["cache"]
+  end
+
+  def pack?
+    !!builder_config["pack"]
+  end
+
+  def args
+    builder_config["args"] || {}
+  end
+
+  def secrets
+    (builder_config["secrets"] || []).to_h { |key| [ key, config.secrets[key] ] }
+  end
+
+  def dockerfile
+    builder_config["dockerfile"] || "Dockerfile"
+  end
+
+  def target
+    builder_config["target"]
+  end
+
+  def context
+    builder_config["context"] || "."
+  end
+
+  def driver
+    builder_config.fetch("driver", "docker-container")
+  end
+
+  def pack_builder
+    builder_config["pack"]["builder"] if pack?
+  end
+
+  def pack_buildpacks
+    builder_config["pack"]["buildpacks"] if pack?
+  end
+
+  def local_disabled?
+    builder_config["local"] == false
+  end
+
+  def cache_from
+    if cached?
+      case builder_config["cache"]["type"]
+      when "gha"
+        cache_from_config_for_gha
+      when "registry"
+        cache_from_config_for_registry
+      end
+    end
+  end
+
+  def cache_to
+    if cached?
+      case builder_config["cache"]["type"]
+      when "gha"
+        cache_to_config_for_gha
+      when "registry"
+        cache_to_config_for_registry
+      end
+    end
+  end
+
+  def ssh
+    builder_config["ssh"]
+  end
+
+  def provenance
+    builder_config["provenance"]
+  end
+
+  def sbom
+    builder_config["sbom"]
+  end
+
+  def git_clone?
+    Kamal::Git.used? && builder_config["context"].nil?
+  end
+
+  def clone_directory
+    @clone_directory ||= File.join Dir.tmpdir, "kamal-clones", [ service, pwd_sha ].compact.join("-")
+  end
+
+  def build_directory
+    @build_directory ||=
+      if git_clone?
+        File.join clone_directory, repo_basename, repo_relative_pwd
+      else
+        "."
+      end
+  end
+
+  def docker_driver?
+    driver == "docker"
+  end
+
+  private
+    def valid?
+      if docker_driver?
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support remote builders" if remote
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support caching" if cached?
+        raise ArgumentError, "Invalid builder configuration: the `docker` driver does not not support multiple arches" if arches.many?
+      end
+
+      if @options["cache"] && @options["cache"]["type"]
+        raise ArgumentError, "Invalid cache type: #{@options["cache"]["type"]}" unless [ "gha", "registry" ].include?(@options["cache"]["type"])
+      end
+    end
+
+    def cache_image
+      builder_config["cache"]&.fetch("image", nil) || "#{image}-build-cache"
+    end
+
+    def cache_image_ref
+      [ server, cache_image ].compact.join("/")
+    end
+
+    def cache_options
+      builder_config["cache"]&.fetch("options", nil)
+    end
+
+    def cache_from_config_for_gha
+      individual_options = cache_options&.split(",") || []
+      allowed_options = individual_options.select { |option| option =~ /^(url|url_v2|token|scope|timeout)=/ }
+
+      [ "type=gha", *allowed_options ].compact.join(",")
+    end
+
+    def cache_from_config_for_registry
+      [ "type=registry", "ref=#{cache_image_ref}" ].compact.join(",")
+    end
+
+    def cache_to_config_for_gha
+      [ "type=gha", cache_options ].compact.join(",")
+    end
+
+    def cache_to_config_for_registry
+      [ "type=registry", "ref=#{cache_image_ref}", cache_options ].compact.join(",")
+    end
+
+    def repo_basename
+      File.basename(Kamal::Git.root)
+    end
+
+    def repo_relative_pwd
+      Dir.pwd.delete_prefix(Kamal::Git.root)
+    end
+
+    def pwd_sha
+      Digest::SHA256.hexdigest(Dir.pwd)[0..12]
+    end
+
+    def default_arch
+      docker_driver? ? [] : [ "amd64", "arm64" ]
+    end
+end

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

@@ -0,0 +1,160 @@
+# Accessories
+#
+# Accessories can be booted on a single host, a list of hosts, or on specific roles.
+# The hosts do not need to be defined in the Kamal servers configuration.
+#
+# Accessories are managed separately from the main service — they are not updated
+# when you deploy, and they do not have zero-downtime deployments.
+#
+# Run `kamal accessory boot <accessory>` to boot an accessory.
+# See `kamal accessory --help` for more information.
+
+# Configuring accessories
+#
+# First, define the accessory in the `accessories`:
+accessories:
+  mysql:
+
+    # Service name
+    #
+    # This is used in the service label and defaults to `<service>-<accessory>`,
+    # where `<service>` is the main service name from the root configuration:
+    service: mysql
+
+    # Image
+    #
+    # The Docker image to use.
+    # Prefix it with its server when using root level registry different from Docker Hub.
+    # Define registry directly or via anchors when it differs from root level registry.
+    image: mysql:8.0
+
+    # Registry
+    #
+    # By default accessories use Docker Hub registry.
+    # You can specify different registry per accessory with this option.
+    # Don't prefix image with this registry server.
+    # Use anchors if you need to set the same specific registry for several accessories.
+    #
+    # ```yml
+    # registry:
+    #   <<: *specific-registry
+    # ```
+    #
+    # See kamal docs registry for more information:
+    registry:
+      ...
+
+    # Accessory hosts
+    #
+    # Specify one of `host`, `hosts`, `role`, `roles`, `tag` or `tags`:
+    host: mysql-db1
+    hosts:
+      - mysql-db1
+      - mysql-db2
+    role: mysql
+    roles:
+      - mysql
+    tag: writer
+    tags:
+      - writer
+      - reader
+
+    # Custom command
+    #
+    # You can set a custom command to run in the container if you do not want to use the default:
+    cmd: "bin/mysqld"
+
+    # Port mappings
+    #
+    # See [https://docs.docker.com/network/](https://docs.docker.com/network/), and
+    # especially note the warning about the security implications of exposing ports publicly.
+    port: "127.0.0.1:3306:3306"
+
+    # Labels
+    labels:
+      app: myapp
+
+    # Options
+    #
+    # These are passed to the Docker run command in the form `--<name> <value>`:
+    options:
+      restart: always
+      cpus: 2
+
+    # Environment variables
+    #
+    # See kamal docs env for more information:
+    env:
+      ...
+
+    # Copying files
+    #
+    # You can specify files to mount into the container.
+    #
+    # They will be uploaded from the local repo to the host and then mounted.
+    # ERB files will be evaluated before being copied.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
+    files:
+      - config/my.cnf.erb:/etc/mysql/my.cnf
+      - config/myoptions.cnf:/etc/mysql/myoptions.cnf:ro
+      - config/certs:/etc/mysql/certs:ro,Z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    files:
+      - local: config/secret.key
+        remote: /etc/mysql/secret.key
+        mode: "0600"
+        owner: "mysql:mysql"
+      - local: config/ca-cert.pem
+        remote: /etc/mysql/certs/ca-cert.pem
+        mode: "0644"
+        owner: "1000:1000"
+        options: "Z"
+
+    # Directories
+    #
+    # You can specify directories to mount into the container. They will be created on the host
+    # before being mounted.
+    #
+    # You can use the string format: `local:remote` or `local:remote:options`
+    # where the options can be `ro` for read-only or `z`/`Z` for SELinux labels
+    directories:
+      - mysql-logs:/var/log/mysql
+      - mysql-data:/var/lib/mysql:z
+    #
+    # Or you can use the hash format for custom mode and ownership.
+    #
+    # Note: Setting `owner` requires root access:
+    directories:
+      - local: mysql-data
+        remote: /var/lib/mysql
+        mode: "0750"
+        owner: "mysql:mysql"
+      - local: mysql-logs
+        remote: /var/log/mysql
+        mode: "0755"
+        options: "z"
+
+    # Volumes
+    #
+    # Any other volumes to mount, in addition to the files and directories.
+    # They are not created or copied before mounting:
+    volumes:
+      - /path/to/mysql-logs:/var/log/mysql
+
+    # Network
+    #
+    # The network the accessory will be attached to.
+    #
+    # Defaults to kamal:
+    network: custom
+
+    # Proxy
+    #
+    # You can run your accessory behind the Kamal proxy. See kamal docs proxy for more information
+    proxy:
+      ...

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

@@ -0,0 +1,29 @@
+# Aliases
+#
+# Aliases are shortcuts for Kamal commands.
+#
+# For example, for a Rails app, you might open a console with:
+#
+# ```shell
+# kamal app exec -i --reuse "bin/rails console"
+# ```
+#
+# By defining an alias, like this:
+aliases:
+  console: app exec -i --reuse "bin/rails console"
+# You can now open the console with:
+#
+# ```shell
+# kamal console
+# ```
+
+# Configuring aliases
+#
+# Aliases are defined in the root config under the alias key.
+#
+# Each alias is named and can only contain lowercase letters, numbers, dashes, and underscores:
+aliases:
+  uname: app exec -p -q -r web "uname -a"
+#
+# Aliases can include a destination with the `-d` flag:
+  staging_deploy: deploy -d staging

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

@@ -0,0 +1,21 @@
+# Booting
+#
+# When deploying to large numbers of hosts, you might prefer not to restart your services on every host at the same time.
+#
+# Kamal’s default is to boot new containers on all hosts in parallel. However, you can control this with the boot configuration.
+
+boot:
+
+  # The number or percentage of hosts to boot at a time.
+  # This can be an integer (e.g., 3) or a percentage string (e.g., 25%).
+  limit: 25%
+
+  # The number of seconds to wait between booting each group of hosts.
+  wait: 10
+
+  # Whether to boot roles in parallel on a host.
+  #
+  # If a host has multiple roles, control whether they are booted in parallel or sequentially on that host.
+  #
+  # Defaults to false.
+  parallel_roles: true

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

@@ -0,0 +1,132 @@
+# Builder
+#
+# The builder configuration controls how the application is built with `docker build`.
+#
+# See https://kamal-deploy.org/docs/configuration/builder-examples/ for more information.
+
+# Builder options
+#
+# Options go under the builder key in the root configuration.
+builder:
+
+  # Arch
+  #
+  # The architectures to build for — you can set an array or just a single value.
+  #
+  # Allowed values are `amd64` and `arm64`:
+  arch:
+    - amd64
+
+  # Remote
+  #
+  # The connection string for a remote builder. If supplied, Kamal 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
+  # the local architecture.
+  #
+  # Defaults to true:
+  local: true
+
+  # Buildpack configuration
+  #
+  # The build configuration for using pack to build a Cloud Native Buildpack image.
+  #
+  # For additional buildpack customization options you can create a project descriptor
+  # file(project.toml) that the Pack CLI will automatically use.
+  # See https://buildpacks.io/docs/for-app-developers/how-to/build-inputs/use-project-toml/ for more information.
+  pack:
+    builder: heroku/builder:24
+    buildpacks:
+      - heroku/ruby
+      - heroku/procfile
+
+  # Builder cache
+  #
+  # The type must be either 'gha' or 'registry'.
+  #
+  # The image is only used for registry cache and is not compatible with the Docker driver:
+  cache:
+    type: registry
+    options: mode=max
+    image: kamal-app-build-cache
+
+  # Build context
+  #
+  # If this is not set, then a local Git clone of the repo is used.
+  # This ensures a clean build with no uncommitted changes.
+  #
+  # To use the local checkout instead, you can set the context to `.`, or a path to another directory.
+  context: .
+
+  # Dockerfile
+  #
+  # The Dockerfile to use for building, defaults to `Dockerfile`:
+  dockerfile: Dockerfile.production
+
+  # Build target
+  #
+  # If not set, then the default target is used:
+  target: production
+
+  # Build arguments
+  #
+  # Any additional build arguments, passed to `docker build` with `--build-arg <key>=<value>`:
+  args:
+    ENVIRONMENT: production
+
+  # Referencing build arguments
+  #
+  # ```shell
+  # ARG RUBY_VERSION
+  # FROM ruby:$RUBY_VERSION-slim as base
+  # ```
+
+  # Build secrets
+  #
+  # Values are read from `.kamal/secrets`:
+  secrets:
+    - SECRET1
+    - SECRET2
+
+  # Referencing build secrets
+  #
+  # ```shell
+  # # Copy Gemfiles
+  # COPY Gemfile Gemfile.lock ./
+  #
+  # # Install dependencies, including private repositories via access token
+  # # Then remove bundle cache with exposed GITHUB_TOKEN
+  # RUN --mount=type=secret,id=GITHUB_TOKEN \
+  #   BUNDLE_GITHUB__COM=x-access-token:$(cat /run/secrets/GITHUB_TOKEN) \
+  #   bundle install && \
+  #   rm -rf /usr/local/bundle/cache
+  # ```
+
+  # SSH
+  #
+  # SSH agent socket or keys to expose to the build:
+  ssh: default=$SSH_AUTH_SOCK
+
+  # Driver
+  #
+  # The build driver to use, defaults to `docker-container`:
+  driver: docker
+  #
+  # If you want to use Docker Build Cloud (https://www.docker.com/products/build-cloud/), you can set the driver to:
+  driver: cloud org-name/builder-name
+
+  # Provenance
+  #
+  # It is used to configure provenance attestations for the build result.
+  # The value can also be a boolean to enable or disable provenance attestations.
+  provenance: mode=max
+
+  # SBOM (Software Bill of Materials)
+  #
+  # It is used to configure SBOM generation for the build result.
+  # The value can also be a boolean to enable or disable SBOM generation.
+  sbom: true