kamal 0.16.0

data/lib/kamal/cli/templates/deploy.yml

@@ -0,0 +1,74 @@
+# Name of your application. Used to uniquely configure containers.
+service: my-app
+
+# Name of the container image.
+image: user/my-app
+
+# Deploy to these servers.
+servers:
+  - 192.168.0.1
+
+# Credentials for your image host.
+registry:
+  # Specify the registry server, if you're not using Docker Hub
+  # server: registry.digitalocean.com / ghcr.io / ...
+  username: my-user
+
+  # Always use an access token rather than real password when possible.
+  password:
+    - KAMAL_REGISTRY_PASSWORD
+
+# Inject ENV variables into containers (secrets come from .env).
+# env:
+#   clear:
+#     DB_HOST: 192.168.0.2
+#   secret:
+#     - RAILS_MASTER_KEY
+
+# Use a different ssh user than root
+# ssh:
+#   user: app
+
+# Configure builder setup.
+# builder:
+#   args:
+#     RUBY_VERSION: 3.2.0
+#   secrets:
+#     - GITHUB_TOKEN
+#   remote:
+#     arch: amd64
+#     host: ssh://app@192.168.0.1
+
+# Use accessory services (secrets come from .env).
+# accessories:
+#   db:
+#     image: mysql:8.0
+#     host: 192.168.0.2
+#     port: 3306
+#     env:
+#       clear:
+#         MYSQL_ROOT_HOST: '%'
+#       secret:
+#         - MYSQL_ROOT_PASSWORD
+#     files:
+#       - config/mysql/production.cnf:/etc/mysql/my.cnf
+#       - db/production.sql.erb:/docker-entrypoint-initdb.d/setup.sql
+#     directories:
+#       - data:/var/lib/mysql
+#   redis:
+#     image: redis:7.0
+#     host: 192.168.0.2
+#     port: 6379
+#     directories:
+#       - data:/data
+
+# Configure custom arguments for Traefik
+# traefik:
+#   args:
+#     accesslog: true
+#     accesslog.format: json
+
+# Configure a custom healthcheck (default is /up on port 3000)
+# healthcheck:
+#   path: /healthz
+#   port: 4000

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

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# A sample post-deploy hook
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+# KAMAL_RUNTIME
+
+echo "$KAMAL_PERFORMER deployed $KAMAL_VERSION to $KAMAL_DESTINATION in $KAMAL_RUNTIME seconds"

data/lib/kamal/cli/templates/sample_hooks/pre-build.sample

@@ -0,0 +1,51 @@
+#!/bin/sh
+
+# A sample pre-build hook
+#
+# Checks:
+# 1. We have a clean checkout
+# 2. A remote is configured
+# 3. The branch has been pushed to the remote
+# 4. The version we are deploying matches the remote
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Git checkout is not clean, aborting..." >&2
+  git status --porcelain >&2
+  exit 1
+fi
+
+first_remote=$(git remote)
+
+if [ -z "$first_remote" ]; then
+  echo "No git remote set, aborting..." >&2
+  exit 1
+fi
+
+current_branch=$(git branch --show-current)
+
+if [ -z "$current_branch" ]; then
+  echo "No git remote set, aborting..." >&2
+  exit 1
+fi
+
+remote_head=$(git ls-remote $first_remote --tags $current_branch | cut -f1)
+
+if [ -z "$remote_head" ]; then
+  echo "Branch not pushed to remote, aborting..." >&2
+  exit 1
+fi
+
+if [ "$KAMAL_VERSION" != "$remote_head" ]; then
+  echo "Version ($KAMAL_VERSION) does not match remote HEAD ($remote_head), aborting..." >&2
+  exit 1
+fi
+
+exit 0

data/lib/kamal/cli/templates/sample_hooks/pre-connect.sample

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+# A sample pre-connect check
+#
+# Warms DNS before connecting to hosts in parallel
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+# KAMAL_RUNTIME
+
+hosts = ENV["KAMAL_HOSTS"].split(",")
+results = nil
+max = 3
+
+elapsed = Benchmark.realtime do
+  results = hosts.map do |host|
+    Thread.new do
+      tries = 1
+
+      begin
+        Socket.getaddrinfo(host, 0, Socket::AF_UNSPEC, Socket::SOCK_STREAM, nil, Socket::AI_CANONNAME)
+      rescue SocketError
+        if tries < max
+          puts "Retrying DNS warmup: #{host}"
+          tries += 1
+          sleep rand
+          retry
+        else
+          puts "DNS warmup failed: #{host}"
+          host
+        end
+      end
+
+      tries
+    end
+  end.map(&:value)
+end
+
+retries = results.sum - hosts.size
+nopes = results.count { |r| r == max }
+
+puts "Prewarmed %d DNS lookups in %.2f sec: %d retries, %d failures" % [ hosts.size, elapsed, retries, nopes ]

data/lib/kamal/cli/templates/sample_hooks/pre-deploy.sample

@@ -0,0 +1,109 @@
+#!/usr/bin/env ruby
+
+# A sample pre-deploy hook
+#
+# Checks the Github status of the build, waiting for a pending build to complete for up to 720 seconds.
+#
+# Fails unless the combined status is "success"
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_COMMAND
+# KAMAL_SUBCOMMAND
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+
+# Only check the build status for production deployments
+if ENV["KAMAL_COMMAND"] == "rollback" || ENV["KAMAL_DESTINATION"] != "production"
+  exit 0
+end
+
+require "bundler/inline"
+
+# true = install gems so this is fast on repeat invocations
+gemfile(true, quiet: true) do
+  source "https://rubygems.org"
+
+  gem "octokit"
+  gem "faraday-retry"
+end
+
+MAX_ATTEMPTS = 72
+ATTEMPTS_GAP = 10
+
+def exit_with_error(message)
+  $stderr.puts message
+  exit 1
+end
+
+class GithubStatusChecks
+  attr_reader :remote_url, :git_sha, :github_client, :combined_status
+
+  def initialize
+    @remote_url = `git config --get remote.origin.url`.strip.delete_prefix("https://github.com/")
+    @git_sha = `git rev-parse HEAD`.strip
+    @github_client = Octokit::Client.new(access_token: ENV["GITHUB_TOKEN"])
+    refresh!
+  end
+
+  def refresh!
+    @combined_status = github_client.combined_status(remote_url, git_sha)
+  end
+
+  def state
+    combined_status[:state]
+  end
+
+  def first_status_url
+    first_status = combined_status[:statuses].find { |status| status[:state] == state }
+    first_status && first_status[:target_url]
+  end
+
+  def complete_count
+    combined_status[:statuses].count { |status| status[:state] != "pending"}
+  end
+
+  def total_count
+    combined_status[:statuses].count
+  end
+
+  def current_status
+    if total_count > 0
+      "Completed #{complete_count}/#{total_count} checks, see #{first_status_url} ..."
+    else
+      "Build not started..."
+    end
+  end
+end
+
+
+$stdout.sync = true
+
+puts "Checking build status..."
+attempts = 0
+checks = GithubStatusChecks.new
+
+begin
+  loop do
+    case checks.state
+    when "success"
+      puts "Checks passed, see #{checks.first_status_url}"
+      exit 0
+    when "failure"
+      exit_with_error "Checks failed, see #{checks.first_status_url}"
+    when "pending"
+      attempts += 1
+    end
+
+    exit_with_error "Checks are still pending, gave up after #{MAX_ATTEMPTS * ATTEMPTS_GAP} seconds" if attempts == MAX_ATTEMPTS
+
+    puts checks.current_status
+    sleep(ATTEMPTS_GAP)
+    checks.refresh!
+  end
+rescue Octokit::NotFound
+  exit_with_error "Build status could not be found"
+end

data/lib/kamal/cli/templates/template.env

@@ -0,0 +1,2 @@
+KAMAL_REGISTRY_PASSWORD=change-this
+RAILS_MASTER_KEY=another-env

data/lib/kamal/cli/traefik.rb

@@ -0,0 +1,111 @@
+class Kamal::Cli::Traefik < Kamal::Cli::Base
+  desc "boot", "Boot Traefik on servers"
+  def boot
+    mutating do
+      on(KAMAL.traefik_hosts) do
+        execute *KAMAL.registry.login
+        execute *KAMAL.traefik.start_or_run
+      end
+    end
+  end
+
+  desc "reboot", "Reboot Traefik on servers (stop container, remove container, start new container)"
+  option :rolling, type: :boolean, default: false, desc: "Reboot traefik on hosts in sequence, rather than in parallel"
+  def reboot
+    mutating do
+      on(KAMAL.traefik_hosts, in: options[:rolling] ? :sequence : :parallel) do
+        execute *KAMAL.auditor.record("Rebooted traefik"), verbosity: :debug
+        execute *KAMAL.registry.login
+        execute *KAMAL.traefik.stop
+        execute *KAMAL.traefik.remove_container
+        execute *KAMAL.traefik.run
+      end
+    end
+  end
+
+  desc "start", "Start existing Traefik container on servers"
+  def start
+    mutating do
+      on(KAMAL.traefik_hosts) do
+        execute *KAMAL.auditor.record("Started traefik"), verbosity: :debug
+        execute *KAMAL.traefik.start
+      end
+    end
+  end
+
+  desc "stop", "Stop existing Traefik container on servers"
+  def stop
+    mutating do
+      on(KAMAL.traefik_hosts) do
+        execute *KAMAL.auditor.record("Stopped traefik"), verbosity: :debug
+        execute *KAMAL.traefik.stop
+      end
+    end
+  end
+
+  desc "restart", "Restart existing Traefik container on servers"
+  def restart
+    mutating do
+      stop
+      start
+    end
+  end
+
+  desc "details", "Show details about Traefik container from servers"
+  def details
+    on(KAMAL.traefik_hosts) { |host| puts_by_host host, capture_with_info(*KAMAL.traefik.info), type: "Traefik" }
+  end
+
+  desc "logs", "Show log lines from Traefik on servers"
+  option :since, aliases: "-s", desc: "Show logs since timestamp (e.g. 2013-01-02T13:23:37Z) or relative (e.g. 42m for 42 minutes)"
+  option :lines, type: :numeric, aliases: "-n", desc: "Number of log lines to pull from each server"
+  option :grep, aliases: "-g", desc: "Show lines with grep match only (use this to fetch specific requests by id)"
+  option :follow, aliases: "-f", desc: "Follow logs on primary server (or specific host set by --hosts)"
+  def logs
+    grep = options[:grep]
+
+    if options[:follow]
+      run_locally do
+        info "Following logs on #{KAMAL.primary_host}..."
+        info KAMAL.traefik.follow_logs(host: KAMAL.primary_host, grep: grep)
+        exec KAMAL.traefik.follow_logs(host: KAMAL.primary_host, grep: grep)
+      end
+    else
+      since = options[:since]
+      lines = options[:lines].presence || ((since || grep) ? nil : 100) # Default to 100 lines if since or grep isn't set
+
+      on(KAMAL.traefik_hosts) do |host|
+        puts_by_host host, capture(*KAMAL.traefik.logs(since: since, lines: lines, grep: grep)), type: "Traefik"
+      end
+    end
+  end
+
+  desc "remove", "Remove Traefik container and image from servers"
+  def remove
+    mutating do
+      stop
+      remove_container
+      remove_image
+    end
+  end
+
+  desc "remove_container", "Remove Traefik container from servers", hide: true
+  def remove_container
+    mutating do
+      on(KAMAL.traefik_hosts) do
+        execute *KAMAL.auditor.record("Removed traefik container"), verbosity: :debug
+        execute *KAMAL.traefik.remove_container
+      end
+    end
+  end
+
+  desc "remove_image", "Remove Traefik image from servers", hide: true
+  def remove_image
+    mutating do
+      on(KAMAL.traefik_hosts) do
+        execute *KAMAL.auditor.record("Removed traefik image"), verbosity: :debug
+        execute *KAMAL.traefik.remove_image
+      end
+    end
+  end
+end

data/lib/kamal/cli.rb

@@ -0,0 +1,7 @@
+module Kamal::Cli
+  class LockError < StandardError; end
+  class HookError < StandardError; end
+end
+
+# SSHKit uses instance eval, so we need a global const for ergonomics
+KAMAL = Kamal::Commander.new

data/lib/kamal/commander.rb

@@ -0,0 +1,154 @@
+require "active_support/core_ext/enumerable"
+require "active_support/core_ext/module/delegation"
+
+class Kamal::Commander
+  attr_accessor :verbosity, :holding_lock, :hold_lock_on_error
+
+  def initialize
+    self.verbosity = :info
+    self.holding_lock = false
+    self.hold_lock_on_error = false
+  end
+
+  def config
+    @config ||= Kamal::Configuration.create_from(**@config_kwargs).tap do |config|
+      @config_kwargs = nil
+      configure_sshkit_with(config)
+    end
+  end
+
+  def configure(**kwargs)
+    @config, @config_kwargs = nil, kwargs
+  end
+
+  attr_reader :specific_roles, :specific_hosts
+
+  def specific_primary!
+    self.specific_hosts = [ config.primary_web_host ]
+  end
+
+  def specific_roles=(role_names)
+    @specific_roles = config.roles.select { |r| role_names.include?(r.name) } if role_names.present?
+  end
+
+  def specific_hosts=(hosts)
+    @specific_hosts = config.all_hosts & hosts if hosts.present?
+  end
+
+  def primary_host
+    specific_hosts&.first || specific_roles&.first&.primary_host || config.primary_web_host
+  end
+
+  def roles
+    (specific_roles || config.roles).select do |role|
+      ((specific_hosts || config.all_hosts) & role.hosts).any?
+    end
+  end
+
+  def hosts
+    (specific_hosts || config.all_hosts).select do |host|
+      (specific_roles || config.roles).flat_map(&:hosts).include?(host)
+    end
+  end
+
+  def boot_strategy
+    if config.boot.limit.present?
+      { in: :groups, limit: config.boot.limit, wait: config.boot.wait }
+    else
+      {}
+    end
+  end
+
+  def roles_on(host)
+    roles.select { |role| role.hosts.include?(host.to_s) }.map(&:name)
+  end
+
+  def traefik_hosts
+    specific_hosts || config.traefik_hosts
+  end
+
+  def accessory_hosts
+    specific_hosts || config.accessories.flat_map(&:hosts)
+  end
+
+  def accessory_names
+    config.accessories&.collect(&:name) || []
+  end
+
+
+  def app(role: nil)
+    Kamal::Commands::App.new(config, role: role)
+  end
+
+  def accessory(name)
+    Kamal::Commands::Accessory.new(config, name: name)
+  end
+
+  def auditor(**details)
+    Kamal::Commands::Auditor.new(config, **details)
+  end
+
+  def builder
+    @builder ||= Kamal::Commands::Builder.new(config)
+  end
+
+  def docker
+    @docker ||= Kamal::Commands::Docker.new(config)
+  end
+
+  def healthcheck
+    @healthcheck ||= Kamal::Commands::Healthcheck.new(config)
+  end
+
+  def hook
+    @hook ||= Kamal::Commands::Hook.new(config)
+  end
+
+  def lock
+    @lock ||= Kamal::Commands::Lock.new(config)
+  end
+
+  def prune
+    @prune ||= Kamal::Commands::Prune.new(config)
+  end
+
+  def registry
+    @registry ||= Kamal::Commands::Registry.new(config)
+  end
+
+  def traefik
+    @traefik ||= Kamal::Commands::Traefik.new(config)
+  end
+
+  def with_verbosity(level)
+    old_level = self.verbosity
+
+    self.verbosity = level
+    SSHKit.config.output_verbosity = level
+
+    yield
+  ensure
+    self.verbosity = old_level
+    SSHKit.config.output_verbosity = old_level
+  end
+
+  def holding_lock?
+    self.holding_lock
+  end
+
+  def hold_lock_on_error?
+    self.hold_lock_on_error
+  end
+
+  private
+    # Lazy setup of SSHKit
+    def configure_sshkit_with(config)
+      SSHKit::Backend::Netssh.pool.idle_timeout = config.sshkit.pool_idle_timeout
+      SSHKit::Backend::Netssh.configure do |sshkit|
+        sshkit.max_concurrent_starts = config.sshkit.max_concurrent_starts
+        sshkit.ssh_options = config.ssh.options
+      end
+      SSHKit.config.command_map[:docker] = "docker" # No need to use /usr/bin/env, just clogs up the logs
+      SSHKit.config.output_verbosity = verbosity
+    end
+end

data/lib/kamal/commands/accessory.rb

@@ -0,0 +1,113 @@
+class Kamal::Commands::Accessory < Kamal::Commands::Base
+  attr_reader :accessory_config
+  delegate :service_name, :image, :hosts, :port, :files, :directories, :cmd,
+           :publish_args, :env_args, :volume_args, :label_args, :option_args, to: :accessory_config
+
+  def initialize(config, name:)
+    super(config)
+    @accessory_config = config.accessory(name)
+  end
+
+  def run
+    docker :run,
+      "--name", service_name,
+      "--detach",
+      "--restart", "unless-stopped",
+      *config.logging_args,
+      *publish_args,
+      *env_args,
+      *volume_args,
+      *label_args,
+      *option_args,
+      image,
+      cmd
+  end
+
+  def start
+    docker :container, :start, service_name
+  end
+
+  def stop
+    docker :container, :stop, service_name
+  end
+
+  def info
+    docker :ps, *service_filter
+  end
+
+
+  def logs(since: nil, lines: nil, grep: nil)
+    pipe \
+      docker(:logs, service_name, (" --since #{since}" if since), (" --tail #{lines}" if lines), "--timestamps", "2>&1"),
+      ("grep '#{grep}'" if grep)
+  end
+
+  def follow_logs(grep: nil)
+    run_over_ssh \
+      pipe \
+        docker(:logs, service_name, "--timestamps", "--tail", "10", "--follow", "2>&1"),
+        (%(grep "#{grep}") if grep)
+  end
+
+
+  def execute_in_existing_container(*command, interactive: false)
+    docker :exec,
+      ("-it" if interactive),
+      service_name,
+      *command
+  end
+
+  def execute_in_new_container(*command, interactive: false)
+    docker :run,
+      ("-it" if interactive),
+      "--rm",
+      *env_args,
+      *volume_args,
+      image,
+      *command
+  end
+
+  def execute_in_existing_container_over_ssh(*command)
+    run_over_ssh execute_in_existing_container(*command, interactive: true)
+  end
+
+  def execute_in_new_container_over_ssh(*command)
+    run_over_ssh execute_in_new_container(*command, interactive: true)
+  end
+
+  def run_over_ssh(command)
+    super command, host: hosts.first
+  end
+
+
+  def ensure_local_file_present(local_file)
+    if !local_file.is_a?(StringIO) && !Pathname.new(local_file).exist?
+      raise "Missing file: #{local_file}"
+    end
+  end
+
+  def make_directory_for(remote_file)
+    make_directory Pathname.new(remote_file).dirname.to_s
+  end
+
+  def make_directory(path)
+    [ :mkdir, "-p", path ]
+  end
+
+  def remove_service_directory
+    [ :rm, "-rf", service_name ]
+  end
+
+  def remove_container
+    docker :container, :prune, "--force", *service_filter
+  end
+
+  def remove_image
+    docker :image, :rm, "--force", image
+  end
+
+  private
+    def service_filter
+      [ "--filter", "label=service=#{service_name}" ]
+    end
+end