kamal 0.16.0

data/lib/kamal/cli/base.rb

@@ -0,0 +1,171 @@
+require "thor"
+require "dotenv"
+require "kamal/sshkit_with_ext"
+
+module Kamal::Cli
+  class Base < Thor
+    include SSHKit::DSL
+
+    def self.exit_on_failure?() true end
+
+    class_option :verbose, type: :boolean, aliases: "-v", desc: "Detailed logging"
+    class_option :quiet, type: :boolean, aliases: "-q", desc: "Minimal logging"
+
+    class_option :version, desc: "Run commands against a specific app version"
+
+    class_option :primary, type: :boolean, aliases: "-p", desc: "Run commands only on primary host instead of all"
+    class_option :hosts, aliases: "-h", desc: "Run commands on these hosts instead of all (separate by comma)"
+    class_option :roles, aliases: "-r", desc: "Run commands on these roles instead of all (separate by comma)"
+
+    class_option :config_file, aliases: "-c", default: "config/deploy.yml", desc: "Path to config file"
+    class_option :destination, aliases: "-d", desc: "Specify destination to be used for config file (staging -> deploy.staging.yml)"
+
+    class_option :skip_hooks, aliases: "-H", type: :boolean, default: false, desc: "Don't run hooks"
+
+    def initialize(*)
+      super
+      load_envs
+      initialize_commander(options_with_subcommand_class_options)
+    end
+
+    private
+      def load_envs
+        if destination = options[:destination]
+          Dotenv.load(".env.#{destination}", ".env")
+        else
+          Dotenv.load(".env")
+        end
+      end
+
+      def options_with_subcommand_class_options
+        options.merge(@_initializer.last[:class_options] || {})
+      end
+
+      def initialize_commander(options)
+        KAMAL.tap do |commander|
+          if options[:verbose]
+            ENV["VERBOSE"] = "1" # For backtraces via cli/start
+            commander.verbosity = :debug
+          end
+
+          if options[:quiet]
+            commander.verbosity = :error
+          end
+
+          commander.configure \
+            config_file: Pathname.new(File.expand_path(options[:config_file])),
+            destination: options[:destination],
+            version: options[:version]
+
+          commander.specific_hosts    = options[:hosts]&.split(",")
+          commander.specific_roles    = options[:roles]&.split(",")
+          commander.specific_primary! if options[:primary]
+        end
+      end
+
+      def print_runtime
+        started_at = Time.now
+        yield
+        return Time.now - started_at
+      ensure
+        runtime = Time.now - started_at
+        puts "  Finished all in #{sprintf("%.1f seconds", runtime)}"
+      end
+
+      def mutating
+        return yield if KAMAL.holding_lock?
+
+        KAMAL.config.ensure_env_available
+
+        run_hook "pre-connect"
+
+        acquire_lock
+
+        begin
+          yield
+        rescue
+          if KAMAL.hold_lock_on_error?
+            error "  \e[31mDeploy lock was not released\e[0m"
+          else
+            release_lock
+          end
+
+          raise
+        end
+
+        release_lock
+      end
+
+      def acquire_lock
+        raise_if_locked do
+          say "Acquiring the deploy lock...", :magenta
+          on(KAMAL.primary_host) { execute *KAMAL.lock.acquire("Automatic deploy lock", KAMAL.config.version), verbosity: :debug }
+        end
+
+        KAMAL.holding_lock = true
+      end
+
+      def release_lock
+        say "Releasing the deploy lock...", :magenta
+        on(KAMAL.primary_host) { execute *KAMAL.lock.release, verbosity: :debug }
+
+        KAMAL.holding_lock = false
+      end
+
+      def raise_if_locked
+        yield
+      rescue SSHKit::Runner::ExecuteError => e
+        if e.message =~ /cannot create directory/
+          on(KAMAL.primary_host) { puts capture_with_debug(*KAMAL.lock.status) }
+          raise LockError, "Deploy lock found"
+        else
+          raise e
+        end
+      end
+
+      def hold_lock_on_error
+        if KAMAL.hold_lock_on_error?
+          yield
+        else
+          KAMAL.hold_lock_on_error = true
+          yield
+          KAMAL.hold_lock_on_error = false
+        end
+      end
+
+      def run_hook(hook, **extra_details)
+        if !options[:skip_hooks] && KAMAL.hook.hook_exists?(hook)
+          details = { hosts: KAMAL.hosts.join(","), command: command, subcommand: subcommand }
+
+          say "Running the #{hook} hook...", :magenta
+          run_locally do
+            KAMAL.with_verbosity(:debug) { execute *KAMAL.hook.run(hook, **details, **extra_details) }
+          rescue SSHKit::Command::Failed
+            raise HookError.new("Hook `#{hook}` failed")
+          end
+        end
+      end
+
+      def command
+        @kamal_command ||= begin
+          invocation_class, invocation_commands = *first_invocation
+          if invocation_class == Kamal::Cli::Main
+            invocation_commands[0]
+          else
+            Kamal::Cli::Main.subcommand_classes.find { |command, clazz| clazz == invocation_class }[0]
+          end
+        end
+      end
+
+      def subcommand
+        @kamal_subcommand ||= begin
+          invocation_class, invocation_commands = *first_invocation
+          invocation_commands[0] if invocation_class != Kamal::Cli::Main
+        end
+      end
+
+      def first_invocation
+        instance_variable_get("@_invocations").first
+      end
+    end
+end

data/lib/kamal/cli/build.rb

@@ -0,0 +1,106 @@
+class Kamal::Cli::Build < Kamal::Cli::Base
+  class BuildError < StandardError; end
+
+  desc "deliver", "Build app and push app image to registry then pull image on servers"
+  def deliver
+    mutating do
+      push
+      pull
+    end
+  end
+
+  desc "push", "Build and push app image to registry"
+  def push
+    mutating do
+      cli = self
+
+      verify_local_dependencies
+      run_hook "pre-build"
+
+      if (uncommitted_changes = Kamal::Utils.uncommitted_changes).present?
+        say "The following paths have uncommitted changes:\n #{uncommitted_changes}", :yellow
+      end
+
+      run_locally do
+        begin
+          KAMAL.with_verbosity(:debug) do
+            execute *KAMAL.builder.push
+          end
+        rescue SSHKit::Command::Failed => e
+          if e.message =~ /(no builder)|(no such file or directory)/
+            error "Missing compatible builder, so creating a new one first"
+
+            if cli.create
+              KAMAL.with_verbosity(:debug) { execute *KAMAL.builder.push }
+            end
+          else
+            raise
+          end
+        end
+      end
+    end
+  end
+
+  desc "pull", "Pull app image from registry onto servers"
+  def pull
+    mutating do
+      on(KAMAL.hosts) do
+        execute *KAMAL.auditor.record("Pulled image with version #{KAMAL.config.version}"), verbosity: :debug
+        execute *KAMAL.builder.clean, raise_on_non_zero_exit: false
+        execute *KAMAL.builder.pull
+      end
+    end
+  end
+
+  desc "create", "Create a build setup"
+  def create
+    mutating do
+      run_locally do
+        begin
+          debug "Using builder: #{KAMAL.builder.name}"
+          execute *KAMAL.builder.create
+        rescue SSHKit::Command::Failed => e
+          if e.message =~ /stderr=(.*)/
+            error "Couldn't create remote builder: #{$1}"
+            false
+          else
+            raise
+          end
+        end
+      end
+    end
+  end
+
+  desc "remove", "Remove build setup"
+  def remove
+    mutating do
+      run_locally do
+        debug "Using builder: #{KAMAL.builder.name}"
+        execute *KAMAL.builder.remove
+      end
+    end
+  end
+
+  desc "details", "Show build setup"
+  def details
+    run_locally do
+      puts "Builder: #{KAMAL.builder.name}"
+      puts capture(*KAMAL.builder.info)
+    end
+  end
+
+  private
+    def verify_local_dependencies
+      run_locally do
+        begin
+          execute *KAMAL.builder.ensure_local_dependencies_installed
+        rescue SSHKit::Command::Failed => e
+          build_error = e.message =~ /command not found/ ?
+            "Docker is not installed locally" :
+            "Docker buildx plugin is not installed locally"
+
+          raise BuildError, build_error
+        end
+      end
+    end
+end

data/lib/kamal/cli/healthcheck.rb

@@ -0,0 +1,20 @@
+class Kamal::Cli::Healthcheck < Kamal::Cli::Base
+  default_command :perform
+
+  desc "perform", "Health check current app version"
+  def perform
+    on(KAMAL.primary_host) do
+      begin
+        execute *KAMAL.healthcheck.run
+        Kamal::Utils::HealthcheckPoller.wait_for_healthy { capture_with_info(*KAMAL.healthcheck.status) }
+      rescue Kamal::Utils::HealthcheckPoller::HealthcheckError => e
+        error capture_with_info(*KAMAL.healthcheck.logs)
+        error capture_with_pretty_json(*KAMAL.healthcheck.container_health_log)
+        raise
+      ensure
+        execute *KAMAL.healthcheck.stop, raise_on_non_zero_exit: false
+        execute *KAMAL.healthcheck.remove, raise_on_non_zero_exit: false
+      end
+    end
+  end
+end

data/lib/kamal/cli/lock.rb

@@ -0,0 +1,37 @@
+class Kamal::Cli::Lock < Kamal::Cli::Base
+  desc "status", "Report lock status"
+  def status
+    handle_missing_lock do
+      on(KAMAL.primary_host) { puts capture_with_debug(*KAMAL.lock.status) }
+    end
+  end
+
+  desc "acquire", "Acquire the deploy lock"
+  option :message, aliases: "-m", type: :string, desc: "A lock message", required: true
+  def acquire
+    message = options[:message]
+    raise_if_locked do
+      on(KAMAL.primary_host) { execute *KAMAL.lock.acquire(message, KAMAL.config.version), verbosity: :debug }
+      say "Acquired the deploy lock"
+    end
+  end
+
+  desc "release", "Release the deploy lock"
+  def release
+    handle_missing_lock do
+      on(KAMAL.primary_host) { execute *KAMAL.lock.release, verbosity: :debug }
+      say "Released the deploy lock"
+    end
+  end
+
+  private
+    def handle_missing_lock
+      yield
+    rescue SSHKit::Runner::ExecuteError => e
+      if e.message =~ /No such file or directory/
+        say "There is no deploy lock"
+      else
+        raise
+      end
+    end
+end

data/lib/kamal/cli/main.rb

@@ -0,0 +1,249 @@
+class Kamal::Cli::Main < Kamal::Cli::Base
+  desc "setup", "Setup all accessories and deploy app to servers"
+  def setup
+    print_runtime do
+      mutating do
+        invoke "kamal:cli:server:bootstrap"
+        invoke "kamal:cli:accessory:boot", [ "all" ]
+        deploy
+      end
+    end
+  end
+
+  desc "deploy", "Deploy app to servers"
+  option :skip_push, aliases: "-P", type: :boolean, default: false, desc: "Skip image build and push"
+  def deploy
+    runtime = print_runtime do
+      mutating do
+        invoke_options = deploy_options
+
+        say "Log into image registry...", :magenta
+        invoke "kamal:cli:registry:login", [], invoke_options
+
+        if options[:skip_push]
+          say "Pull app image...", :magenta
+          invoke "kamal:cli:build:pull", [], invoke_options
+        else
+          say "Build and push app image...", :magenta
+          invoke "kamal:cli:build:deliver", [], invoke_options
+        end
+
+        run_hook "pre-deploy"
+
+        say "Ensure Traefik is running...", :magenta
+        invoke "kamal:cli:traefik:boot", [], invoke_options
+
+        say "Ensure app can pass healthcheck...", :magenta
+        invoke "kamal:cli:healthcheck:perform", [], invoke_options
+
+        say "Detect stale containers...", :magenta
+        invoke "kamal:cli:app:stale_containers", [], invoke_options
+
+        invoke "kamal:cli:app:boot", [], invoke_options
+
+        say "Prune old containers and images...", :magenta
+        invoke "kamal:cli:prune:all", [], invoke_options
+      end
+    end
+
+    run_hook "post-deploy", runtime: runtime.round
+  end
+
+  desc "redeploy", "Deploy app to servers without bootstrapping servers, starting Traefik, pruning, and registry login"
+  option :skip_push, aliases: "-P", type: :boolean, default: false, desc: "Skip image build and push"
+  def redeploy
+    runtime = print_runtime do
+      mutating do
+        invoke_options = deploy_options
+
+        if options[:skip_push]
+          say "Pull app image...", :magenta
+          invoke "kamal:cli:build:pull", [], invoke_options
+        else
+          say "Build and push app image...", :magenta
+          invoke "kamal:cli:build:deliver", [], invoke_options
+        end
+
+        run_hook "pre-deploy"
+
+        say "Ensure app can pass healthcheck...", :magenta
+        invoke "kamal:cli:healthcheck:perform", [], invoke_options
+
+        say "Detect stale containers...", :magenta
+        invoke "kamal:cli:app:stale_containers", [], invoke_options
+
+        invoke "kamal:cli:app:boot", [], invoke_options
+      end
+    end
+
+    run_hook "post-deploy", runtime: runtime.round
+  end
+
+  desc "rollback [VERSION]", "Rollback app to VERSION"
+  def rollback(version)
+    rolled_back = false
+    runtime = print_runtime do
+      mutating do
+        invoke_options = deploy_options
+
+        KAMAL.config.version = version
+        old_version = nil
+
+        if container_available?(version)
+          run_hook "pre-deploy"
+
+          invoke "kamal:cli:app:boot", [], invoke_options.merge(version: version)
+          rolled_back = true
+        else
+          say "The app version '#{version}' is not available as a container (use 'kamal app containers' for available versions)", :red
+        end
+      end
+    end
+
+    run_hook "post-deploy", runtime: runtime.round if rolled_back
+  end
+
+  desc "details", "Show details about all containers"
+  def details
+    invoke "kamal:cli:traefik:details"
+    invoke "kamal:cli:app:details"
+    invoke "kamal:cli:accessory:details", [ "all" ]
+  end
+
+  desc "audit", "Show audit log from servers"
+  def audit
+    on(KAMAL.hosts) do |host|
+      puts_by_host host, capture_with_info(*KAMAL.auditor.reveal)
+    end
+  end
+
+  desc "config", "Show combined config (including secrets!)"
+  def config
+    run_locally do
+      puts Kamal::Utils.redacted(KAMAL.config.to_h).to_yaml
+    end
+  end
+
+  desc "init", "Create config stub in config/deploy.yml and env stub in .env"
+  option :bundle, type: :boolean, default: false, desc: "Add Kamal to the Gemfile and create a bin/kamal binstub"
+  def init
+    require "fileutils"
+
+    if (deploy_file = Pathname.new(File.expand_path("config/deploy.yml"))).exist?
+      puts "Config file already exists in config/deploy.yml (remove first to create a new one)"
+    else
+      FileUtils.mkdir_p deploy_file.dirname
+      FileUtils.cp_r Pathname.new(File.expand_path("templates/deploy.yml", __dir__)), deploy_file
+      puts "Created configuration file in config/deploy.yml"
+    end
+
+    unless (deploy_file = Pathname.new(File.expand_path(".env"))).exist?
+      FileUtils.cp_r Pathname.new(File.expand_path("templates/template.env", __dir__)), deploy_file
+      puts "Created .env file"
+    end
+
+    unless (hooks_dir = Pathname.new(File.expand_path(".kamal/hooks"))).exist?
+      hooks_dir.mkpath
+      Pathname.new(File.expand_path("templates/sample_hooks", __dir__)).each_child do |sample_hook|
+        FileUtils.cp sample_hook, hooks_dir, preserve: true
+      end
+      puts "Created sample hooks in .kamal/hooks"
+    end
+
+    if options[:bundle]
+      if (binstub = Pathname.new(File.expand_path("bin/kamal"))).exist?
+        puts "Binstub already exists in bin/kamal (remove first to create a new one)"
+      else
+        puts "Adding Kamal to Gemfile and bundle..."
+        run_locally do
+          execute :bundle, :add, :kamal
+          execute :bundle, :binstubs, :kamal
+        end
+        puts "Created binstub file in bin/kamal"
+      end
+    end
+  end
+
+  desc "envify", "Create .env by evaluating .env.erb (or .env.staging.erb -> .env.staging when using -d staging)"
+  def envify
+    if destination = options[:destination]
+      env_template_path = ".env.#{destination}.erb"
+      env_path          = ".env.#{destination}"
+    else
+      env_template_path = ".env.erb"
+      env_path          = ".env"
+    end
+
+    File.write(env_path, ERB.new(File.read(env_template_path)).result, perm: 0600)
+  end
+
+  desc "remove", "Remove Traefik, app, accessories, and registry session from servers"
+  option :confirmed, aliases: "-y", type: :boolean, default: false, desc: "Proceed without confirmation question"
+  def remove
+    mutating do
+      if options[:confirmed] || ask("This will remove all containers and images. Are you sure?", limited_to: %w( y N ), default: "N") == "y"
+        invoke "kamal:cli:traefik:remove", [], options.without(:confirmed)
+        invoke "kamal:cli:app:remove", [], options.without(:confirmed)
+        invoke "kamal:cli:accessory:remove", [ "all" ], options
+        invoke "kamal:cli:registry:logout", [], options.without(:confirmed)
+      end
+    end
+  end
+
+  desc "version", "Show Kamal version"
+  def version
+    puts Kamal::VERSION
+  end
+
+  desc "accessory", "Manage accessories (db/redis/search)"
+  subcommand "accessory", Kamal::Cli::Accessory
+
+  desc "app", "Manage application"
+  subcommand "app", Kamal::Cli::App
+
+  desc "build", "Build application image"
+  subcommand "build", Kamal::Cli::Build
+
+  desc "healthcheck", "Healthcheck application"
+  subcommand "healthcheck", Kamal::Cli::Healthcheck
+
+  desc "lock", "Manage the deploy lock"
+  subcommand "lock", Kamal::Cli::Lock
+
+  desc "prune", "Prune old application images and containers"
+  subcommand "prune", Kamal::Cli::Prune
+
+  desc "registry", "Login and -out of the image registry"
+  subcommand "registry", Kamal::Cli::Registry
+
+  desc "server", "Bootstrap servers with curl and Docker"
+  subcommand "server", Kamal::Cli::Server
+
+  desc "traefik", "Manage Traefik load balancer"
+  subcommand "traefik", Kamal::Cli::Traefik
+
+  private
+    def container_available?(version)
+      begin
+        on(KAMAL.hosts) do
+          KAMAL.roles_on(host).each do |role|
+            container_id = capture_with_info(*KAMAL.app(role: role).container_id_for_version(version))
+            raise "Container not found" unless container_id.present?
+          end
+        end
+      rescue SSHKit::Runner::ExecuteError => e
+        if e.message =~ /Container not found/
+          say "Error looking for container version #{version}: #{e.message}"
+          return false
+        else
+          raise
+        end
+      end
+
+      true
+    end
+
+    def deploy_options
+      { "version" => KAMAL.config.version }.merge(options.without("skip_push"))
+    end
+end

data/lib/kamal/cli/prune.rb

@@ -0,0 +1,30 @@
+class Kamal::Cli::Prune < Kamal::Cli::Base
+  desc "all", "Prune unused images and stopped containers"
+  def all
+    mutating do
+      containers
+      images
+    end
+  end
+
+  desc "images", "Prune dangling images"
+  def images
+    mutating do
+      on(KAMAL.hosts) do
+        execute *KAMAL.auditor.record("Pruned images"), verbosity: :debug
+        execute *KAMAL.prune.dangling_images
+        execute *KAMAL.prune.tagged_images
+      end
+    end
+  end
+
+  desc "containers", "Prune all stopped containers, except the last 5"
+  def containers
+    mutating do
+      on(KAMAL.hosts) do
+        execute *KAMAL.auditor.record("Pruned containers"), verbosity: :debug
+        execute *KAMAL.prune.containers
+      end
+    end
+  end
+end

data/lib/kamal/cli/registry.rb

@@ -0,0 +1,18 @@
+class Kamal::Cli::Registry < Kamal::Cli::Base
+  desc "login", "Log in to registry locally and remotely"
+  def login
+    run_locally    { execute *KAMAL.registry.login }
+    on(KAMAL.hosts) { execute *KAMAL.registry.login }
+  # FIXME: This rescue needed?
+  rescue ArgumentError => e
+    puts e.message
+  end
+
+  desc "logout", "Log out of registry remotely"
+  def logout
+    on(KAMAL.hosts) { execute *KAMAL.registry.logout }
+  # FIXME: This rescue needed?
+  rescue ArgumentError => e
+    puts e.message
+  end
+end

data/lib/kamal/cli/server.rb

@@ -0,0 +1,21 @@
+class Kamal::Cli::Server < Kamal::Cli::Base
+  desc "bootstrap", "Set up Docker to run Kamal apps"
+  def bootstrap
+    missing = []
+
+    on(KAMAL.hosts | KAMAL.accessory_hosts) do |host|
+      unless execute(*KAMAL.docker.installed?, raise_on_non_zero_exit: false)
+        if execute(*KAMAL.docker.superuser?, raise_on_non_zero_exit: false)
+          info "Missing Docker on #{host}. Installing…"
+          execute *KAMAL.docker.install
+        else
+          missing << host
+        end
+      end
+    end
+
+    if missing.any?
+      raise "Docker is not installed on #{missing.join(", ")} and can't be automatically installed without having root access and the `curl` command available. Install Docker manually: https://docs.docker.com/engine/install/"
+    end
+  end
+end