cartage-remote 1.1 → 2.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8d8ac39718d7abe3c0091abb06c8d3ecb456626e
-  data.tar.gz: a143524b851528d44b9dde9f77a9946c76ca2b1e
+  metadata.gz: a407715cfc69a80ee22680f2bd2596987503a27f
+  data.tar.gz: aa30045f89581ac22feb52783e326cbfb43c26d0
 SHA512:
-  metadata.gz: 7a36d402c39713f5e0c1d4337cc52e7a7d57ddf74db363add86ca1e0c8db08d876603b58c1e099f8782507dd3ee9fec0fcce42311ccab03502f73aed318d0814
-  data.tar.gz: 395e90926c44b60f527398084938f8755679110c2b404211975d74077068a5881598f8b504c54e7c2d50705c1af829561242a0c6f03e422010f10183412eb97d
+  metadata.gz: 790d60ff41276adef303b1b3dac7374a688db17cb3c7db93b32dafcfbb775c3410c8bb41c097ba133ce4baacbf552c2d37f4b7957ceb90756844c1062da2257d
+  data.tar.gz: 3db9359ef4e88f7fe29e999009c72364518c38671eb4fa55e0dc85505d97cfce33ea1018efc13b31ae9ad04c55a278259c8de2956f0b6ffccf512e22e1b1cb57

data/Contributing.md

@@ -0,0 +1,68 @@
+## Contributing
+
+We value any contribution to cartage-remote you can provide: a bug report, a
+feature request, or code contributions. cartage-remote is reasonably complex
+code, so there are a few contribution guidelines:
+
+*   Changes *will not* be accepted without tests. The test suite is written
+    with [Minitest][].
+*   Match our coding style.
+*   Use a thoughtfully-named topic branch that contains your change. Rebase
+    your commits into logical chunks as necessary.
+*   Use [quality commit messages][].
+*   Do not change the version number; when your patch is accepted and a release
+    is made, the version will be updated at that point.
+*   Submit a GitHub pull request with your changes.
+
+### Test Dependencies
+
+cartage-remote uses Ryan Davis’s [Hoe][] to manage the release process, and it
+adds a number of rake tasks. You will mostly be interested in:
+
+    $ rake
+
+which runs the tests the same way that:
+
+    $ rake test
+    $ rake travis
+
+will do.
+
+To assist with the installation of the development dependencies for
+cartage-remote, I have provided the simplest possible Gemfile pointing to the
+(generated) `cartage-remote.gemspec` file. This will permit you to do:
+
+    $ bundle install
+
+to get the development dependencies. If you aleady have `hoe` installed, you
+can accomplish the same thing with:
+
+    $ rake newb
+
+This task will install any missing dependencies, run the tests/specs, and
+generate the RDoc.
+
+### Workflow
+
+Here's the most direct way to get your work merged into the project:
+
+*   Fork the project.
+*   Clone down your fork (`git clone
+    git://github.com/KineticCafe/cartage-remote.git`).
+*   Create a topic branch to contain your change (`git checkout -b
+    my_awesome_feature`).
+*   Hack away, add tests. Not necessarily in that order.
+*   Make sure everything still passes by running `rake`.
+*   If necessary, rebase your commits into logical chunks, without errors.
+*   Push the branch up (`git push origin my_awesome_feature`).
+*   Create a pull request against KineticCafe/cartage-remote and describe
+    what your change does and the why you think it should be merged.
+
+### Contributors
+
+*   Austin Ziegler created cartage-remote.
+
+[Minitest]: https://github.com/seattlerb/minitest
+[quality commit messages]: http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html
+[Hoe]: https://github.com/seattlerb/hoe
+[kccoc]: https://github.com/KineticCafe/code-of-conduct

data/{History.rdoc → History.md}

@@ -1,3 +1,14 @@
+=== 2.0 / 2016-03-DD
+
+*   Rewrote for compatibility with cartage 2.0.
+
+*   1 major enhancements
+
+    *   Configuration now supports multiple servers. Old cartage-remote
+        configurations will continue to work and be accessible as the +default+
+        host. An error will be raised if there is an explicit +default+
+        host combined with this implicit +default+ host.
+
 === 1.1 / 2015-03-26
 
 *   1 major bugfix

data/{Licence.rdoc → Licence.md}

@@ -1,8 +1,8 @@
-== Licence
+## Licence
 
 This software is available under an MIT-style licence.
 
-* Copyright 2015 Kinetic Cafe
+*   Copyright 2015–2016 Kinetic Cafe
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in
@@ -11,9 +11,9 @@ use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
 of the Software, and to permit persons to whom the Software is furnished to do
 so, subject to the following conditions:
 
-* The names of its contributors may not be used to endorse or promote
-  products derived from this software without specific prior written
-  permission.
+*   The names of its contributors may not be used to endorse or promote
+    products derived from this software without specific prior written
+    permission.
 
 The above copyright notice and this permission notice shall be included in all
 copies or substantial portions of the Software.

data/Manifest.txt

@@ -1,12 +1,11 @@
-.autotest
-.gemtest
-.minitest.rb
-Contributing.rdoc
-Gemfile
-History.rdoc
-Licence.rdoc
+Contributing.md
+History.md
+Licence.md
 Manifest.txt
 README.rdoc
 Rakefile
-lib/cartage/remote.rb
-lib/cartage/remote/command.rb
+lib/cartage/commands/remote.rb
+lib/cartage/plugins/remote.rb
+lib/cartage/remote/host.rb
+test/minitest_config.rb
+test/test_cartage_remote.rb

data/README.rdoc

@@ -2,7 +2,7 @@
 
 code :: https://github.com/KineticCafe/cartage-remote/
 issues :: https://github.com/KineticCafe/cartage-remote/issues
-continuous integration :: {<img src="https://travis-ci.org/KineticCafe/cartage-remote.png" />}[https://travis-ci.org/KineticCafe/cartage-remote]
+continuous integration :: {<img src="https://travis-ci.org/KineticCafe/cartage-remote.svg?branch=master" alt="Build Status" />}[https://travis-ci.org/KineticCafe/cartage-remote]
 
 == Description
 
@@ -11,20 +11,35 @@ to build a package on a remote machine with cartage.
 
 Cartage provides a repeatable means to create a package for a Rails application
 that can be used in deployment with a configuration tool like Ansible, Chef,
-Puppet, or Salt. The package is created with its dependencies bundled in
-`vendor/bundle`, so it can be deployed in environments with strict access
-control rules and without requiring development tool access.
+Puppet, or Salt.
 
-== Synopsis
+== Synopsis & Configuration
+
+cartage-remote is a plug-in for Cartage that builds a package on a remote
+machine.
 
     # Build a package on a remote machine via SSH.
     cartage remote
 
+This can be configured in the <tt>config.remote</tt> section of the Cartage
+configuration file.
+
+    plugins:
+      remote:
+        disabled: false
+        host: default
+        hosts:
+          default:
+            user: build
+            address: build-machine
+            port: 22
+          alternate: alternate@build-machine:2222
+
 == Install
 
 Add cartage-remote to your Gemfile:
 
-    gem 'cartage-remote', '~> 1.1'
+    gem 'cartage-remote', '~> 2.0'
 
 Or manually install:
 
@@ -37,9 +52,13 @@ change:
 
 * When PATCH is zero (+0+), it will be omitted from version references.
 
-cartage-remote will generally track cartage for major versions to ensure plugin API
-compatibility.
+cartage-remote will generally track cartage for major versions to ensure plugin
+API compatibility.
 
-:include: Contributing.rdoc
+== Community and Contributing
 
-:include: Licence.rdoc
+cartage-bundler welcomes your contributions as described in
+{Contributing.md}[https://github.com/KineticCafe/cartage-bundler/blob/master/Contributing.md].
+This project, like all Kinetic Cafe {open source
+projects}[https://github.com/KineticCafe], is under the Kinetic Cafe Open
+Source {Code of Conduct}[https://github.com/KineticCafe/code-of-conduct].

data/Rakefile

@@ -1,53 +1,70 @@
-# -*- ruby -*-
+# frozen_string_literal: true
 
 require 'rubygems'
 require 'hoe'
-require 'pathname'
+require 'rake/clean'
 
 Hoe.plugin :doofus
-Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
+Hoe.plugin :email unless ENV['CI'] || ENV['TRAVIS']
 Hoe.plugin :gemspec2
 Hoe.plugin :git
 Hoe.plugin :minitest
 Hoe.plugin :rubygems
+Hoe.plugin :travis
 
 spec = Hoe.spec 'cartage-remote' do
   developer('Austin Ziegler', 'aziegler@kineticcafe.com')
 
-  self.history_file = 'History.rdoc'
+  self.history_file = 'History.md'
   self.readme_file = 'README.rdoc'
-  self.extra_rdoc_files = FileList['*.rdoc'].to_a
 
   license 'MIT'
 
-  self.extra_deps << ['cartage', '~> 1.1']
-  self.extra_deps << ['micromachine', '~> 1.2']
-  self.extra_deps << ['fog', '~> 1.27']
-
-  self.extra_dev_deps << ['rake', '~> 10.0']
-  self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
-  self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
-  self.extra_dev_deps << ['hoe-git', '~> 1.5']
-  self.extra_dev_deps << ['hoe-geminabox', '~> 0.3']
-  self.extra_dev_deps << ['minitest', '~> 5.4']
-  self.extra_dev_deps << ['minitest-autotest', '~> 1.0']
-  self.extra_dev_deps << ['minitest-bisect', '~> 1.2']
-  self.extra_dev_deps << ['minitest-focus', '~> 1.1']
-  self.extra_dev_deps << ['minitest-moar', '~> 0.0']
-  self.extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
-  self.extra_dev_deps << ['simplecov', '~> 0.7']
+  ruby20!
+
+  extra_deps << ['cartage', '~> 2.0.rc1']
+  extra_deps << ['micromachine', '~> 2.0']
+  extra_deps << ['fog', '~> 1.27']
+  extra_deps << ['net-ssh', '~> 3.0']
+  extra_deps << ['net-scp', '~> 1.2']
+
+  extra_dev_deps << ['rake', '>= 10.0']
+  extra_dev_deps << ['rdoc', '~> 4.2']
+  extra_dev_deps << ['hoe-doofus', '~> 1.0']
+  extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
+  extra_dev_deps << ['hoe-git', '~> 1.5']
+  extra_dev_deps << ['hoe-travis', '~> 1.2']
+  extra_dev_deps << ['minitest', '~> 5.4']
+  extra_dev_deps << ['minitest-autotest', '~> 1.0']
+  extra_dev_deps << ['minitest-bisect', '~> 1.2']
+  extra_dev_deps << ['minitest-bonus-assertions', '~> 2.0']
+  extra_dev_deps << ['minitest-focus', '~> 1.1']
+  extra_dev_deps << ['minitest-moar', '~> 0.0']
+  extra_dev_deps << ['minitest-pretty_diff', '~> 0.1']
+  extra_dev_deps << ['simplecov', '~> 0.7']
+end
+
+ENV['RUBYOPT'] = '-W0'
+
+module Hoe::Publish #:nodoc:
+  alias __make_rdoc_cmd__cartage__ make_rdoc_cmd
+
+  def make_rdoc_cmd(*extra_args) # :nodoc:
+    spec.extra_rdoc_files.delete_if { |f| f == 'Manifest.txt' }
+    __make_rdoc_cmd__cartage__(*extra_args)
+  end
 end
 
 namespace :test do
-  task :coverage do
-    prelude = <<-EOS
-require 'simplecov'
-SimpleCov.start('test_frameworks') { command_name 'Minitest' }
-gem 'minitest'
-    EOS
-    spec.test_prelude = prelude.split($/).join('; ')
-    Rake::Task['test'].execute
+  if File.exist?('.simplecov-prelude.rb')
+    task :coverage do
+      spec.test_prelude = 'load ".simplecov-prelude.rb"'
+
+      Rake::Task['test'].execute
+    end
   end
+
+  CLOBBER << 'coverage'
 end
 
-# vim: syntax=ruby
+CLOBBER << 'tmp'

data/lib/cartage/commands/remote.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+Cartage::CLI.extend do
+  desc 'Build packages on remote servers'
+  long_desc <<-'DESC'
+Resolve Cartage configuration locally, then execute a build script on the
+configured remote server based on the resolved configuration.
+  DESC
+  command 'remote' do |remote|
+    remote.desc 'The name of the remote server to use'
+    remote.long_desc <<-'DESC'
+The name of the defined remote server in the Cartage configuration file. If the
+server does not exist in the configuration, an error will be reported.
+    DESC
+    remote.flag %i(H host), arg_name: :HOST, default_value: :default
+
+    remote.desc 'Check plugin configuration'
+    remote.long_desc <<-'DESC'
+Verifies the configuration of the cartage-remote section of the Cartage
+configuration file.
+    DESC
+    remote.command 'check-config' do |check|
+      check.hide!
+      check.action do |_global, _options, _args|
+        cartage.remote.check_config
+      end
+    end
+
+    remote.default_desc 'Run a build script remotely'
+    remote.action do |_global, options, _args|
+      options[:host] = nil if options[:host] == :default
+      config = cartage.config(for_plugin: :remote)
+      server = (options[:host] || config.host || :default).to_sym
+
+      unless config.dig(:hosts, server)
+        message = if options[:host] || config.host
+                    "Host '#{server}' does not exist."
+                  else
+                    'Default host does not exist.'
+                  end
+        fail ArgumentError, message
+      end
+
+      config.server = server
+      cartage.remote.build
+    end
+  end
+end

data/lib/cartage/plugins/remote.rb

@@ -0,0 +1,475 @@
+# frozen_string_literal: true
+
+require 'tempfile'
+require 'micromachine'
+require 'cartage/plugin'
+
+# A reliable way to create packages.
+class Cartage
+  # Connect to a remote machine and build a package remotely. cartage-remote
+  # uses Fog::SSH with key-based authentication (not password-based) to connect
+  # to a remote server.
+  #
+  # cartage-remote assumes a relatively stable build server, but does not
+  # require one (custom +prebuild+ and +postbuild+ scripts could be used to
+  # manage that).
+  #
+  # == Remote Build Isolation
+  #
+  # cartage-remote allows for safe builds across multiple projects and branches
+  # with path-based isolation. The pattern for the build path is shown below,
+  # where the last part of the path is where the code will be cloned to.
+  #
+  #   ~<remote_user>/cartage/<project-name>/<timestamp>/<project-name>
+  #          |          |           |            |           |
+  #          v          |           |            |           |
+  #     build root      v           |            |           |
+  #                  cartage        |            |           |
+  #                   path          v            |           |
+  #                              project         v           |
+  #                               path       isolation       |
+  #                                             path         v
+  #                                                        build
+  #                                                         path
+  #
+  # So that if I am deploying on a project called +calliope+ and my remote user
+  # is +build+, my isolated build path might be:
+  #
+  #   ~build/cartage/calliope/20160321091432/calliope
+  #
+  # == Remote Build Steps
+  #
+  # The steps for a remote build are:
+  #
+  # 1.  Configure Cartage and save the active Cartage configuration as a
+  #     temporary file that will be copied to the remote server.
+  # 2.  Configure the Fog::SSH and Fog::SCP adapters with the keys to connect
+  #     to the remote system.
+  # 3.  Create the +prebuild+ script and run it locally (where the cartage CLI
+  #     was run).
+  # 4.  Connect to the remote server, put the Cartage configuration file in the
+  #     isolation path, and clone the repository. Check the repo out to the
+  #     appropriate +release_hashref+.
+  # 5.  Create the +build+ script, copy it remotely, and run it from the build
+  #     isolation path (+build_path+). This is effectively:
+  #       cd "$build_path" && $build_script
+  # 6.  Clean up the remote server fromt his build.
+  # 7.  Create the +postbuild+ script and run it locally (where the cartage CLI
+  #     was run).
+  #
+  # == Configuration
+  #
+  # cartage-remote is configured in the +plugins.remote+ section of the Cartage
+  # configuration file. It supports two primary keys:
+  #
+  # +hosts+:: A dictionary of hosts, as described below, that indicate the
+  #           remote machine where the build script will be run. The host keys
+  #           will be used as the +host+ value.
+  # +host+:: The name of the target host to be used. If missing, uses the
+  #          +default+ location.
+  #
+  # For backwards compatibility, a single host may be specified in a +server+
+  # key, using the same format as the +host+ values. This host will become the
+  # +default+ host unless one is already specified in the +hosts+ dictionary
+  # (which is an error).
+  #
+  # The following keys are optional and may be provided globally in
+  # +plugins.remote+, or per host in +plugins.remote.hosts.$name+. If provided,
+  # host-level values override the global configuration.
+  #
+  # +keys+:: The SSH key(s) used to connect to the server. There are two basic
+  #          ways that keys can be provided:
+  #
+  #          * If provided as a string or an array of strings, the value(s)
+  #            will be applied as glob patterns to find key files on disk.
+  #          * If provided as a dictionary, the values are the ASCII
+  #            representations of the private keys.
+  #
+  #          If keys are not provided, keys will be found on the local machine
+  #          using the pattern <tt>~/.ssh/*id_[rd]sa</tt>.
+  # +build+:: A multiline YAML string that is copied to the remote machine and
+  #           executed as a script there. If not provided, the following script
+  #           will be run:
+  #
+  #             #!/bin/bash
+  #             set -e
+  #             if [ -f Gemfile ]; then
+  #               bundle install --path %{remote_bundle}
+  #               bundle exec cartage build \
+  #                 --config-file %{config_file} \
+  #                 --target %{project_path}
+  #             else
+  #               cartage build --config-file %{config_file} \
+  #                 --target %{project_path}
+  #             fi
+  # +prebuild+:: A multiline YAML string that is run as a script on the local
+  #              machine to prepare for running remotely. If not provided, the
+  #              following script will be run:
+  #
+  #                #!/bin/bash
+  #                ssh-keyscan -H %{remote_adddress} >> ~/.ssh/known_hosts
+  # +postbuild+:: A multiline YAML string that is run as a script on the local
+  #               machine to finish the build process locally. There is no
+  #               default postbuild script. The script will be passed the stage
+  #               (+local_config+, +ssh_config+, +prebuild+, +remote_clone+,
+  #               +remote_build+, +cleanup+, or +finished+) and, if the stage
+  #               is not +finished+, the error message.
+  #
+  # === Hosts
+  #
+  # A host describes the remote server. It may be specified either as a string
+  # in the form <tt>[user@]host[:port]</tt> *or* a dictionary with required
+  # keys:
+  #
+  # +user+:: The user to connect to the remote server as. If not provided,
+  #          defaults to +$USER+.
+  # +address+:: The host address for connecting to the remote server. Also
+  #             called +host+.
+  # +port+:: The optional port to connect to the remote server on; used if not
+  #          using the standard SSH port, 22.
+  #
+  # Additionally, +keys+, +build+, +prebuild+, and +postbuild+ scripts may be
+  # specified to override the global scripts.
+  #
+  # == Script Substitution
+  #
+  # The +build+, +prebuild+, and +postbuild+ scripts require information from
+  # the Cartage and Cartage::Remote instances. When these scripts are rendered
+  # to disk, they will be run through Kernel#sprintf with string substitution
+  # parameters (<tt>%{<em>parameter-name</em>}</tt>). All of these values are
+  # computed from the local Cartage configuration.
+  #
+  # +repo_url+:: The repository URL.
+  # +name+:: The package name.
+  # +release_hashref+:: The release hashref to build.
+  # +timestamp+:: The build timestamp.
+  # +remote_address+:: The remote build host. Also available as +remote_host+
+  #                    for backwards compatability.
+  # +remote_port+:: The remote build host SSH port (may be empty).
+  # +remote_user+:: The remote build user.
+  # +build_root+:: The remote build root, (usually
+  #                <tt>~<em>remote_user</em></tt>).
+  # +cartage_path+:: <tt><em>build_root</em>/cartage</tt>.
+  # +project_path+:: <tt><em>cartage_path</em>/<em>name</em></tt>.
+  # +isolation_path+:: <tt><em>project_path</em>/<em>timestamp</em></tt>.
+  # +build_path+:: The remote build path (contains the code to package).
+  #                <tt><em>isolation_path</em>/<em>name</em></tt>
+  # +remote_bundle+:: A place where dependencies for the build can be installed
+  #                   locally. <tt><em>isolation_path</em>/deps</tt>. Typically
+  #                   used in the +build+ script.
+  #                     bundle install --path %{remote_bundle}
+  # +dependency_cache+:: The +dependency_cachevendor_cache+ for the remote
+  #                      server. Set the same as +project_path+.
+  # +config_file+:: The remote filename of the computed Cartage configuration.
+  #                 Must be provided to the remote run of +cartage+.
+  #                   bundle exec cartage build --config-file %{config_file}
+  # +build_script+:: The full path to the remote build script.
+  #                  <tt><em>isolation_path</em>/cartage-build-remote</tt>.
+  #
+  # == Configuration Example
+  #
+  #   ---
+  #   plugins:
+  #     remote:
+  #       hosts:
+  #         default: build-server
+  #       script: |
+  #         #! /bin/bash
+  #         bundle install --path %{remote_bundle} &&
+  #         bundle exec cartage build --config-file %{config_file} &&
+  #         bundle exec cartage s3 --config-file %{config_file}
+  class Remote < Cartage::Plugin
+    VERSION = '2.0.rc1' #:nodoc:
+
+    # Build on the remote server.
+    def build
+      stage.trigger! :local_setup
+      stage.trigger! :ssh_setup
+      stage.trigger! :run_prebuild
+      stage.trigger! :clone_remote
+      stage.trigger! :build_remote
+      stage.trigger! :clean_remote
+      stage.trigger! :complete
+    rescue Cartage::CLI::CustomExit
+      raise
+    rescue => e
+      error = e.exception("Remote error in stage #{stage.state}: #{e.message}")
+      error.set_backtrace(e.backtrace)
+      raise error
+    ensure
+      if postbuild_script
+        cartage.display 'Running postbuild script...'
+        system make_tmpscript('postbuild', postbuild_script, subs).path,
+          stage.state.to_s, error.to_s
+      end
+
+      tmpfiles.each do |tmpfile|
+        tmpfile.close
+        tmpfile.unlink
+      end
+      tmpfiles.clear
+    end
+
+    # Check that the configuration is correct. If +require_host+ is present, an
+    # exception will be thrown if a host is required and not present.
+    def check_config(require_host: false)
+      hosts = cartage.config(for_plugin: :remote).hosts
+      verify_hosts(hosts)
+      fail "No host #{name} present" if require_host && !hosts.dig(name)
+    end
+
+    private
+
+    def initialize(*) #:nodoc:
+      super
+      @host = @name = @keys = @key_data = nil
+
+      @stage = MicroMachine.new('new').tap { |stage|
+        stage.when :local_setup, 'new' => 'local_config'
+        stage.when :ssh_setup, 'local_config' => 'ssh_config'
+        stage.when :run_prebuild, 'ssh_config' => 'prebuild'
+        stage.when :clone_remote, 'prebuild' => 'remote_clone'
+        stage.when :build_remote, 'remote_clone' => 'remote_build'
+        stage.when :clean_remote, 'remote_build' => 'cleanup'
+        stage.when :complete, 'cleanup' => 'finished'
+        stage.on(:any) { |event| dispatch(event, stage.state) }
+      }
+    end
+
+    attr_reader :host
+    attr_reader :name
+    attr_reader :config
+    attr_reader :stage
+
+    attr_reader :build_root
+    attr_reader :config_file
+    attr_reader :key_data
+    attr_reader :keys
+    attr_reader :paths
+    attr_reader :subs
+
+    def prebuild_script
+      unless defined?(@prebuild_script)
+        @prebuild_script = host.prebuild || config.prebuild ||
+          DEFAULT_PREBUILD_SCRIPT
+      end
+      @prebuild_script
+    end
+
+    def postbuild_script
+      unless defined?(@postbuild_script)
+        @postbuild_script = host.postbuild || config.postbuild
+      end
+      @postbuild_script
+    end
+
+    def build_script
+      unless defined?(@build_script)
+        @build_script = host.build || config.build || DEFAULT_BUILD_SCRIPT
+      end
+      @build_script
+    end
+
+    def tmpfiles
+      @tmpfiles ||= []
+    end
+
+    def local_setup
+      @name = config.host || 'default'
+      host_config = config.dig(:hosts, name)
+      verify_host!(name, host_config)
+      @host = Cartage::Remote::Host.new(host_config)
+
+      fail ArgumentError, <<-exception if build_script.nil? || build_script.empty?
+No build script to run on remote #{host}.
+      exception
+
+      # Force lazy values to be present during execution.
+      cartage.send(:realize!)
+
+      cartage.display 'Pre-build configuration...'
+      @paths = OpenStruct.new(build_root: build_root)
+      paths.cartage_path = paths.build_root.join('cartage')
+      paths.project_path = paths.cartage_path.join(cartage.name)
+      paths.isolation_path = paths.project_path.join(cartage.timestamp)
+      paths.build_path = paths.isolation_path.join(cartage.name)
+      paths.remote_bundle = paths.isolation_path.join('deps')
+      paths.dependency_cache = paths.project_path
+      paths.config_file = paths.isolation_path.join('cartage.yml')
+      paths.build_script = paths.isolation_path.join('cartage-build-remote')
+
+      @config_file = make_config(paths).path
+
+      @subs = OpenStruct.new(
+        paths.to_h.merge(
+          repo_url:        cartage.repo_url,
+          name:            cartage.name,
+          release_hashref: cartage.release_hashref,
+          timestamp:       cartage.timestamp,
+          remote_host:     host.address,
+          remote_address:  host.address,
+          remote_port:     host.port,
+          remote_user:     host.user
+        )
+      )
+    end
+
+    def ssh_setup
+      host.configure_ssh(keys: keys, key_data: key_data)
+    end
+
+    def run_prebuild
+      cartage.display 'Running prebuild script...'
+      system(make_tmpscript('prebuild', prebuild_script, subs).path)
+    end
+
+    def clone_remote
+      cartage.display <<-message
+Checking out #{cartage.repo_url} at #{cartage.release_hashref} remotely...
+      message
+
+      ssh "mkdir -p #{paths.isolation_path}"
+      host.scp.upload(config_file, user_path(paths.config_file))
+      ssh "git clone #{cartage.repo_url} #{paths.build_path}"
+      ssh <<-command
+cd #{paths.build_path} && git checkout #{cartage.release_hashref}
+      command
+    end
+
+    def build_remote
+      cartage.display 'Running build script...'
+      script = make_tmpscript('build', build, subs).path
+      host.scp.upload(script, user_path(paths.build_script))
+      ssh "cd #{paths.build_path} && #{paths.build_script}"
+    end
+
+    def clean_remote
+      cartage.display 'Cleaning up after the build...'
+      ssh "rm -rf #{paths.isolation_path}"
+    end
+
+    def dispatch(event, state)
+      send(event) if respond_to?(event, true)
+      send(state) if respond_to?(state, true)
+    end
+
+    def resolve_plugin_config!(remote_config)
+      @config = remote_config
+      if config.dig(:server)
+        if config.dig(:hosts, :default)
+          fail ArgumentError,
+            'Cannot configure both an implicit and explicit default host.'
+        end
+
+        config.hosts ||= OpenStruct.new
+        default = Cartage::Remote::Host.new(config.server).to_hash
+        config.hosts.default ||= OpenStruct.new(default)
+      end
+
+      if config.keys.kind_of?(OpenStruct)
+        @key_data = config.keys.to_h.values
+      else
+        @keys = Array(config.keys || '~/.ssh/*id_[rd]sa').flat_map { |key|
+          Pathname.glob(Pathname(key).expand_path)
+        }
+      end
+
+      @build_root = Pathname(config.build_root || '~')
+      @postbuild_script = config.postbuild
+    end
+
+    def ssh(*commands)
+      results = host.ssh.run(commands) do |stdout, stderr|
+        $stdout.print stdout unless stdout.nil?
+        $stderr.print stderr unless stderr.nil?
+      end
+
+      results.each do |result|
+        next if result.status.zero?
+
+        message = <<-msg
+Remote error in stage #{stage.state}:
+  SSH command failed with status (#{result.status}):
+        #{result.command}
+        msg
+        fail Cartage::CLI::CustomExit.new(message, result.status)
+      end
+    end
+
+    def make_tmpfile(basename, content = nil)
+      Tempfile.new("#{basename}.").tap { |f|
+        f.write content || yield
+        f.close
+        tmpfiles << f
+      }
+    end
+
+    def make_tmpscript(basename, content, subs)
+      make_tmpfile(basename, content % subs.to_h).tap { |f|
+        File.chmod(0700, f.path)
+      }
+    end
+
+    def make_config(paths)
+      make_tmpfile('config.yml') do
+        config = Cartage::Config.new(cartage.config)
+        config.name = cartage.name
+        config.root_path = paths.build_path.to_s
+        config.timestamp = cartage.timestamp
+        config.release_hashref = cartage.release_hashref
+        config.compression = cartage.compression.to_s
+        config.disable_dependency_cache = cartage.disable_dependency_cache
+        config.dependency_cache_path = paths.dependency_cache.to_s
+        config.to_yaml
+      end
+    end
+
+    def user_path(path)
+      path.to_s.sub(%r{\A~/}, '')
+    end
+
+    def verify_hosts(hosts)
+      fail ArgumentError, 'No hosts present' if hosts.nil? || hosts.to_h.empty?
+
+      hosts.each_pair do |name, host|
+        verify_host(name, host)
+      end
+    end
+
+    def verify_host(name, host, &notify)
+      notify ||= ->(message) { warn message }
+
+      case host
+      when OpenStruct
+        host.dig(:address) || host.dig(:host)
+      when String
+        Cartage::Remote::Host::HOST_RE.match(host)[:address]
+      end || notify.("Host #{name} invalid: No host address present")
+    end
+
+    def verify_host!(name, host)
+      verify_host(name, host) { |message| fail ArgumentError, message }
+    end
+
+    DEFAULT_PREBUILD_SCRIPT = <<-script #:nodoc:
+#!/bin/bash
+
+ssh-keyscan -H %{remote_address} >> ~/.ssh/known_hosts
+    script
+
+    DEFAULT_BUILD_SCRIPT = <<-script #:nodoc:
+#!/bin/bash
+
+set -e
+
+if [ -f Gemfile ]; then
+  bundle install --path %{remote_bundle}
+  bundle exec cartage build --config-file %{config_file} --target %{project_path}
+else
+  cartage build --config-file %{config_file} --target %{project_path}
+fi
+    script
+  end
+end
+
+require 'cartage/remote/host'