capistrano-docker_cluster 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b21dd5be728c678022ef6ae1b2bc6034e8610cac1c2152fd3cde26e852e0bc35
+  data.tar.gz: 4a297e06578a06670daab133c6dca12c19d3b2596a82d9f26605d1391adade49
+SHA512:
+  metadata.gz: 5fc892bf4d56e78fabec0603b8e03ae1edbf151d54753fc46abc71d2a5d0272fd46b5612da053c2e6925a7d7e560fa99d024aea4f26bc57c8456236cd38728c1
+  data.tar.gz: 5f903a514ea9366f8f4d502b0b32c2cbe821be92edd8344e9d74519cd19346f09c8a348de8723045bd429b1e5c2106ccfe2b3507cf4f5b5cd3d5c2787d78ff58

data/CHANGE_LOG.md

@@ -0,0 +1,7 @@
+# 1.0.1
+
+* Fix module naming convention to match gem name.
+
+# 1.0.0
+
+* Initial release

data/MIT_LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2020 Brian Durand
+
+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 the Software without restriction, including without limitation the rights
+to 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 above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,155 @@
+# Capistrano Docker Cluster
+
+This gem provides a recipe to use capistrano to deploy docker applications.
+
+This allows you to deploy an application across a cluster of servers running docker. There are, of course, other methods of doing this (kubernetes, docker-compose, etc.). This method can fill a nitch of allowing you to dockerize your application but keep the deployment simple and use existing configs if you're already deploying via capistrano.
+
+You application will be deployed by pulling a tag from a docker repository on the remote servers and then starting it up as a cluster using the `bin/docker_cluster` script. This script will start a cluster of docker containers by spinning up a specified number of containers from the same image and configuration. It does this gracefully by first shutting down any excess containers and then restarting the containers one at a time. The script can perform an optional health check to determine if a container is fully running before shutting down the next contaner.
+
+If you specify a port mapping for the containers, the container ports will be mapped to incrementing host ports so you can run multiple server containers fronted by a load balancer.
+
+The full set of arguments can be found in the `bin/docker-cluster` script.
+
+## Configuration
+
+The deployment is configured with the following properties in your capistrano recipe.
+
+* `docker_repository` - The URI for the repository where to pull images from. If you are building images on the docker host (i.e. for a staging server), this can just be the local respoitory.
+
+* `docker_tag` - The tag of the image to pull for starting the containers.
+
+* `docker_roles` - List of server roles that will run docker containers. This defaults to `:docker`, but you can change it to whatever server roles you have in your recipe.
+
+* `docker_user` - User to use when running docker commands on the remote host. This user must have access to the docker daemon. Default to the default capistrano user.
+
+* `docker_env` - Environment variables needed to run docker commands. You may need to set `HOME` if you are pulling docker images from a remote repository using a use that is not the default deploy user.
+
+* `docker_apps` - List of apps to deploy. Each app is deployed to its own containers with its own configuration. This value should usually be defined on a server role.
+
+* `docker_prefix` - Optional prefix to attach to docker container names. This can be used to distinguish containers where multiple applications are running on the same host with the same `docker_apps` names (for instance, if you run staging containers on the same hardware as your production containers).
+
+* `docker_configs` - List of global configuration files for starting all containers.
+
+* `docker_app_configs` - Map of configuration files for starting specific docker apps.
+
+* `docker_args` - List of global command line arguments for all continers.
+
+* `docker_app_args` - Map of command line arguments for starting specific docker apps.
+
+### Example Configuration
+
+```ruby
+set :docker_repository, repository.example.com/myapp
+
+set :docker_tag, ENV.fetch("tag")
+
+# Define two apps; the web app will run on both server01 and server02
+role :web, [server01, server02], user: 'app', docker_apps: [:web]
+role :async, [server01], user: 'app', docker_apps: [:async]
+
+# These configuration files will apply to all containers
+set :docker_configs, ["config/volumes.properties"]
+
+# Unlike config files, args can be dynamically generated at runtime
+set :docker_args, ["--env=ASSET_HOST=#{ENV.fetch('asset_host')}"]
+
+# These configuration files and args will apply only to each app.
+set :docker_app_configs, {
+  web: ["config/web.properties"],
+  async: ["config/async.properties"]
+}
+
+set :docker_app_args, {
+  web: ["--env=SERVER_HOST=#{fetch(:server_host)}"]
+}
+
+# If your capistrano user doesn't have access to the docker daemon, you can specify a different user.
+set :docker_user, "root"
+
+# You can also specify environment variables that may be needed for running docker commands.
+set :docker_env, {"HOME" => "/root"}
+```
+
+## Server Scripts
+
+Scripts to control your docker applications are put into the `bin` directory in the capistrano target directory. These scripts are wrappers around the `bin/docker-cluster` script and supply the configuration values to that script for each app you've defined.
+
+### bin/start
+
+```bash
+bin/start app [additional arguments]
+```
+
+* The start script will start up the docker containers for you app.
+* If the containers are not running, they will be started.
+* If excess containers are running, they will be stopped.
+* If the containers are running, but they are running on a different image version, they will be replaced one at a time by new containers.
+
+
+### bin/stop
+
+```bash
+bin/stop app
+```
+
+* All the containers associated with the app will be stopped.
+
+### bin/run
+
+```bash
+bin/run app [additional arguments]
+```
+
+* Start a one off container with the specified app config.
+* The normal port mapping used for the cluster will not be included; if you want to expose ports, you'll need to supply the port mapping.
+* All apps defined in `docker_apps` as well as `docker_app_configs` and `docker_app_args` will be included as apps. This allows you to set up things like a "console" app which will open a console on a container for debugging, etc. without having it be part of the cluster apps.
+
+## Capfile and SCM setting
+
+The deployment does not require a source control management system to perform the build. To turn off this feature you need to include this in your project's Capfile to include the Docker deployment recipe and turn off the default (git) SCM setting for capistrano.
+
+```ruby
+  require 'capistrano/docker_cluster'
+  install_plugin Capistrano::Scm::None::Plugin
+```
+
+## Remote Repository
+
+If your `docker_repository` points to a remote repository, then the tag specified by `docker_tag` will be pulled from that repository during the deploy. If the repository requires authentication, then you should implement the `docker:authenticate` task to authenticate all servers in the `docker_role` role with the repository. You can use the `as_docker_user` method to run docker commands as the user specified in `docker_user`.
+
+### Example Authentication with Amazon ECR
+
+```ruby
+namespace :docker do
+  task :authenticate do
+    bin_dir = "#{fetch(:release_path)}/bin"
+    ecr_login_path = "#{bin_dir}/ecr_login"
+    on release_roles(fetch(:docker_roles)) do |host|
+      execute(:mkdir, "-p", bin_dir)
+      upload! StringIO.new(ecr_login_script), ecr_login_path
+      as_docker_user do
+        execute :bash, ecr_login_path
+      end
+    end
+  end
+end
+
+# Script to run the aws ecr get-login results, but with passing the password in
+# via STDIN so that it doesn't appear in the capistrano logs.
+def ecr_login_script
+  <<~BASH
+    #!/usr/bin/env bash
+
+    set -o errexit
+
+    read -sra cmd < <(/usr/bin/env aws ecr get-login --no-include-email)
+    pass="${cmd[5]}"
+    unset cmd[4] cmd[5]
+    /usr/bin/env "${cmd[@]}" --password-stdin <<< "$pass"
+  BASH
+end
+```
+
+## Building Docker Image
+
+If you need to build the docker image on the remote host as part of the deploy (for example if you're deploying pre-release code to a staging server), you can implement the `docker:build` task to build your docker image. You must also tag the image with the value in the `:docker_tag` property.

data/bin/docker-cluster

@@ -0,0 +1,423 @@
+#!/usr/bin/env bash
+
+# Script to manage a cluster of docker containers with the same configuration running on sequential ports.
+#
+# The --name parameter will be used to assign names to the containers as "name.number" where number is the
+# number of the started container starting at 1.
+#
+# The --count paramter can be used to specify the number of containers to start up. If the script finds that
+# more than that number of containers are already running, it will first shut down the excess containers.
+# It will then shutdown the running containers one at a time and start up a new one before shutting down the
+# next container.
+#
+# The --image parameter specifies the docker image to start up. It can be either a tag or an image id. This
+# parameter is required if --count is greater than zero.
+#
+# The --port paramters specifies port mapping in the form "container_port:base_host_port" where container
+# port is the exposed port to map from the containers. The base host port is the port number to start mapping
+# the container ports to. If the base host port is not specified, then the container port will be used as the
+# base host port. For instance, `--port=80:8000 --count=2` will start two containers with the first one mapping
+# host port 8000 to container port 80 and the second mapping host port 8001 to container port 80.
+#
+# The --hostname parameter can be used to specify a base host name for the containers. The host name for each
+# container will be "container_name.base_host_hamer" where container name uses a hyphen instead of a period as
+# the delimiter.
+#
+# The --healthcheck parameter can be used to specify either a command to run inside the container or a URL
+# to ping from within the container to determine if the container is up. The next container will not be shutdown
+# until the previous one is determined to be up when this parameter is specified.
+#
+# The --timeout parameter can be used to specify a timeout for how long to wait for a container to stop or start
+# before assuming something is wrong. In the case of stopping the container, the container will be force killed
+# after the specified number of seconds. If starting a container times out, then the restart script will be stopped
+# at that point and no more containers will be restarted.
+#
+# The --config parameter can be used to specify a file that contains more command line arguments for this script. This
+# parameter can be specified multiple times. The files should be property files in the form "arg=val" or "arg val" or "arg"
+# on each line. Comments can be used in the configuration files using "#".
+#
+# The --command parameter can be used to specify the command each docker container should run. If multiple command parameters
+# are specified, they will be concatenated together. You can use this to specify a command and arguments separately.
+#
+# The --force parameter can be used to specify that containers should always be restarted. The default behavior
+# is to only restart containers if they are not running the specified image.
+#
+# The --one-off parameter can be used to specify that a one off container should be spun up instead of stopping
+# and starting containers in the cluster. Any --port, --hostname, --healthcheck, and --name arguments that appear
+# before this argument will be ignored. If these arguments appear after the --one-off argument, then they will
+# be passed through to the `docker run` command.
+#
+# The --verbose parameter can be used for debugging and will show all the shell commands as they are run.
+#
+# All other parameters are passed through to the `docker run` command.
+
+set -o errexit
+
+usage() {
+  script_name=$(basename $0)
+  echo "Usage: $script_name"
+  echo "  --name CONTAINER_NAME_PREFIX (or --one-off)"
+  echo "  [--count CONTAINER_COUNT] (default 1)"
+  echo "  [--image DOCKER_IMAGE] (image tag or id; required if --count > 0)"
+  echo "  [--port CONTAINER_PORT[:BASE_HOST_PORT]]"
+  echo "  [--hostname CONTAINER_BASE_HOST_NAME]"
+  echo "  [--healthcheck COMMAND|CURL_URL]"
+  echo "  [--timeout SECONDS] (default 120)"
+  echo "  [--config CONFIG_FILE_PATH]"
+  echo "  [--command DOCKER_RUN_COMMAND]"
+  echo "  [--verbose]"
+  echo "  All other options are passed through to 'docker run'"
+}
+
+read_arguments() {
+  while [ "$1" != "" ]; do
+    typeset arg=$1
+    typeset val=
+    if [[ $arg =~ ^--?[^-]+ ]]; then
+      if [[ $arg =~ ^-.+= ]]; then
+        arg="${1%=*}"
+        val="${1#*=}"
+      fi
+    fi
+
+    case $arg in
+      --image )
+        [[ -z $val ]] && shift && val=$1
+        DOCKER_IMAGE=$val
+        ;;
+      --name )
+        [[ -z $val ]] && shift && val=$1
+        CONTAINER_NAME_PREFIX=$val
+        ;;
+      --count )
+        [[ -z $val ]] && shift && val=$1
+        CONTAINER_COUNT=$val
+        ;;
+      --port )
+        [[ -z $val ]] && shift && val=$1
+        PORT_MAPPING+=($val)
+        ;;
+      --hostname )
+        [[ -z $val ]] && shift && val=$1
+        CONTAINER_BASE_HOST_NAME=$val
+        ;;
+      --config )
+        [[ -z $val ]] && shift && val=$1
+        cat "$val" > /dev/null
+        typeset config_args=
+        IFS=$'\n\r' config_args=($(sed 's/#.*//g' "$val" | grep -v '^[[:space:]]*$' | sed 's/^ *//g' | sed -E 's/^([^-])/--\1/g' | sed -E 's/^([^ =]+) /\1=/g'))
+        read_arguments ${config_args[@]}
+        unset IFS
+        ;;
+      --command )
+        [[ -z $val ]] && shift && val=$1
+        DOCKER_RUN_COMMAND="$DOCKER_RUN_COMMAND $val"
+        ;;
+      --one-off )
+        ONE_OFF_CONTAINER="1"
+        CONTAINER_NAME_PREFIX=""
+        CONTAINER_BASE_HOST_NAME=""
+        HEALTHCHECK=""
+        PORT_MAPPING=()
+        ;;
+      --healthcheck )
+        [[ -z $val ]] && shift && val=$1
+        HEALTHCHECK=$val
+        ;;
+      --timeout )
+        [[ -z $val ]] && shift && val=$1
+        TIMEOUT=$val
+        ;;
+      --force )
+        FORCE_RESTART="1"
+        ;;
+      --help )
+        usage
+        exit
+        ;;
+      --verbose )
+        set -o xtrace
+        CMD_OUT=/dev/stdout
+        ;;
+      * )
+        DOCKER_RUN_ARGS="$DOCKER_RUN_ARGS $1"
+    esac
+    shift
+  done
+}
+
+# Return port mapping arguments for docker run. Ports are passed in to
+# the command as `--port base_host_port:container_port`. The host port
+# will be incremented for each container started so each container will
+# be mapped to it's own host port.
+docker_port_args() {
+  typeset port_args=
+  for port_info in "${PORT_MAPPING[@]}"; do
+    typeset split_port=
+    IFS=':' read -ra split_port <<< "$port_info"
+    unset IFS
+    typeset base_port=${split_port[0]}
+    typeset container_port=${split_port[1]}
+    if [[ $container_port == "" ]]; then
+      container_port=$base_port
+    fi
+    typeset host_port=`expr $base_port + $1 - 1`
+    port_args="-p $host_port:$container_port"
+  done
+  echo $port_args
+}
+
+# Run the docker health check command. Returns the exit status of
+# running the command on the specified container. If the command is a
+# URL, then it will be fetched with curl within the container.
+docker_healthcheck() {
+  typeset container_id=$1
+  typeset cmd=$2
+  if [[ $cmd =~ ^https?:// ]]; then
+    cmd="curl --silent --fail $cmd"
+  fi
+  echo `/usr/bin/env docker exec "$container_id" $cmd > /dev/null; echo $?`
+}
+
+# Stop and remove the container specified by the passed in id.
+docker_stop() {
+  typeset container_id=$1
+  echo "> sending stop to container $container_id"
+  /usr/bin/env docker stop $container_id > $CMD_OUT || true
+
+  end_time=(expr `date +%s` + $TIMEOUT)
+  while true; do
+    typeset running_info=$(/usr/bin/env docker ps --no-trunc --filter status=running --format "{{.ID}}" | grep -F "$container_id" | cat)
+    if [[ $running_info == "" ]]; then
+      break
+    fi
+
+    if [[ `date +%s` > $end_time ]]; then
+      exit 1
+    else
+      sleep 1
+    fi
+  done
+
+  # If the container is still running and we didn't send a KILL signal, try that now.
+  typeset running_info=$(/usr/bin/env docker ps --no-trunc --filter status=running --format "{{.ID}}" | grep -F "$container_id" | cat)
+  if [[ $running_info != "" && $STOP_SIGNAL != "SIGKILL" ]]; then
+    echo "> container still running; sending kill to container $container_id"
+    /usr/bin/env docker kill --signal=SIGKILL $container_id > $CMD_OUT
+    sleep 1
+  fi
+
+  /usr/bin/env docker container rm $container_id > $CMD_OUT
+}
+
+# Remove the specified container name from docker.
+docker_remove_container_name() {
+  typeset container_name=$1
+  typeset container_info=$(/usr/bin/env docker container ls --no-trunc --format "{{.ID}};{{.Names}};" | grep -F ";$container_name;" | cat)
+  if [[ $container_info != "" ]]; then
+    typeset info_arr=
+    IFS=';' read -ra info_arr <<< "$container_info"
+    unset IFS
+    typeset container_id=${info_arr[1]}
+    /usr/bin/env docker container rm $container_id > $CMD_OUT
+  fi
+}
+
+# Shutdown containers that are no longer used. Detected by comparing
+# the container numbers in the container name to the number of containers
+# that were requested to start.
+shutdown_excess_containers() {
+  typeset container_names=()
+  for i in $(seq 1 $CONTAINER_COUNT); do
+    container_names+=("$CONTAINER_NAME_PREFIX.$i")
+  done
+
+  typeset container_info=()
+  typeset line=
+  while IFS= read -r line; do
+    container_info+=( "$line" )
+  done < <( /usr/bin/env docker ps --no-trunc --format ";{{.ID}};{{.Names}};" | grep -F ";$CONTAINER_NAME_PREFIX." | cat )
+  unset IFS
+
+  for info in "${container_info[@]}"; do
+    typeset info_arr=
+    IFS=';' read -ra info_arr <<< "$info"
+    unset IFS
+    typeset container_id=${info_arr[1]}
+    typeset container_name=${info_arr[2]}
+    if [[ ! " ${container_names[@]} " =~ " ${container_name} " ]]; then
+      docker_stop $container_id
+    fi
+  done
+}
+
+# Get the image id a container is running.
+container_image_id() {
+  typeset name="$CONTAINER_NAME_PREFIX.$1"
+  typeset running_info=$(/usr/bin/env docker ps --no-trunc --filter status=running --format ";{{.Image}};{{.Names}};" | grep -F ";$name;" | cat)
+  if [[ $running_info != "" ]]; then
+    typeset info_arr=
+    IFS=';' read -ra info_arr <<< "$running_info"
+    unset IFS
+    echo ${info_arr[1]}
+  fi
+}
+
+# Stop the container with the specified name if it is running.
+stop_container() {
+  typeset name="$CONTAINER_NAME_PREFIX.$1"
+  typeset running_info=$(/usr/bin/env docker ps --no-trunc --format ";{{.ID}};{{.Names}};" | grep -F ";$name;" | cat)
+  if [[ $running_info != "" ]]; then
+    typeset info_arr=
+    IFS=';' read -ra info_arr <<< "$running_info"
+    unset IFS
+    typeset container_id=${info_arr[1]}
+    docker_stop $container_id
+  else
+    docker_remove_container_name "$name"
+  fi
+}
+
+start_container() {
+  typeset name="$CONTAINER_NAME_PREFIX.$1"
+  echo "> start container $name"
+  typeset port_args=$(docker_port_args $1)
+  typeset host_arg="${CONTAINER_NAME_PREFIX}-${1}.${CONTAINER_BASE_HOST_NAME}"
+  typeset docker_cmd="/usr/bin/env docker run --detach --name $name --hostname $host_arg $port_args $DOCKER_RUN_ARGS $DOCKER_IMAGE $DOCKER_RUN_COMMAND"
+  typeset container_id=$($docker_cmd)
+  if [[ $container_id == "" ]]; then
+    >&2 echo "container $name failed to start"
+    >&2 echo "  command: $docker_cmd"
+    exit 1
+  else
+    echo "> starting container $name: $container_id"
+  fi
+
+  typeset success=1
+  typeset end_time=(expr `date +%s` + $TIMEOUT)
+  while true; do
+    typeset running_info=$(/usr/bin/env docker ps --no-trunc --filter status=running --format ";{{.ID}};{{.Names}};{{.Status}}" | grep -F ";$name;" | cat)
+    if [[ $running_info == "" ]]; then
+      >&2 echo "container $name not running when it was expected"
+      exit 1
+    fi
+    typeset info_arr=
+    IFS=';' read -ra info_arr <<< "$running_info"
+    unset IFS
+
+    typeset status=${info_arr[3]}
+    if [[ $status == "Up"* ]]; then
+      if [[ $HEALTHCHECK != "" ]]; then
+        healthy=`docker_healthcheck $container_id "$HEALTHCHECK"`
+        if [[ $healthy == "0" ]]; then
+          success=0
+          break
+        fi
+      else
+        if [[ $status == *"health"* ]]; then
+          if [[ $status == *"healthy"* ]]; then
+            success=0
+            break
+          fi
+        else
+          success=0
+          break
+        fi
+      fi
+    fi
+
+    if [[ `date +%s` > $end_time ]]; then
+      break
+    else
+      sleep 1
+    fi
+  done
+
+  if [[ $success ]]; then
+    echo "> container $name up: $container_id"
+  else
+    >&2 echo "container $name did not start up after $TIMEOUT seconds"
+    exit 1
+  fi
+}
+
+one_off_container() {
+  typeset port_args=$(docker_port_args 1)
+  typeset docker_cmd="/usr/bin/env docker run $port_args $DOCKER_RUN_ARGS $DOCKER_IMAGE"
+  if [[ $CONTAINER_NAME_PREFIX != "" ]]; then
+    docker_cmd="$docker_cmd --name $CONTAINER_NAME_PREFIX"
+  fi
+  if [[ $CONTAINER_BASE_HOST_NAME != "" ]]; then
+    docker_cmd="$docker_cmd --hostname $CONTAINER_BASE_HOST_NAME"
+  fi
+  if [[ $DOCKER_RUN_COMMAND != "" ]]; then
+    docker_cmd="$docker_cmd $DOCKER_RUN_COMMAND"
+  fi
+  exec $docker_cmd
+}
+
+###
+### Parse command line options
+###
+
+DOCKER_IMAGE=
+CONTAINER_NAME_PREFIX=
+CONTAINER_COUNT=1
+PORT_MAPPING=()
+DOCKER_RUN_COMMAND=
+HEALTHCHECK=
+TIMEOUT=120
+CMD_OUT=/dev/null
+DOCKER_RUN_ARGS=
+FORCE_RESTART=
+ONE_OFF_CONTAINER=
+
+read_arguments $@
+
+if [[ $ONE_OFF_CONTAINER == "1" ]]; then
+  one_off_container
+fi
+
+if [[ $CONTAINER_NAME_PREFIX == "" ]]; then
+  usage
+  exit 1
+fi
+
+if [[ $CONTAINER_COUNT > 0 ]]; then
+  if [[ $DOCKER_IMAGE == "" ]]; then
+    usage
+    exit 1
+  else
+    typeset image_id=$(/usr/bin/env docker inspect --type=image --format {{.Config.Image}} $DOCKER_IMAGE)
+    if [[ $image_id == "" ]]; then
+      >&2 echo "Could not find image $DOCKER_IMAGE"
+      exit 1
+    else
+      echo "> using image $image_id"
+    fi
+  fi
+fi
+
+if [[ $CONTAINER_BASE_HOST_NAME == "" ]]; then
+  CONTAINER_BASE_HOST_NAME=$(hostname)
+fi
+
+shutdown_excess_containers
+
+if [[ $CONTAINER_COUNT > 0 ]]; then
+  # Cleanup docker environment so there are no surprises
+  /usr/bin/env docker container prune -f > $CMD_OUT
+  for i in $(seq 1 $CONTAINER_COUNT); do
+    typeset image_id=$(container_image_id $i)
+    if [[ $image_id != "" && $image_id == $DOCKER_IMAGE && $FORCE_RESTART == "" ]]; then
+      echo "> container ${CONTAINER_NAME_PREFIX}.${i} already running $DOCKER_IMAGE"
+    else
+      stop_container $i
+      start_container $i
+    fi
+  done
+fi
+
+/usr/bin/env docker ps | grep -F " $CONTAINER_NAME_PREFIX." || true
+
+exit 0

data/capistrano-docker_cluster.gemspec

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+require_relative "lib/capistrano/docker_cluster/version"
+
+Gem::Specification.new do |spec|
+  spec.name          = "capistrano-docker_cluster"
+  spec.version       = Capistrano::DockerCluster::VERSION
+  spec.authors       = ["Brian Durand"]
+  spec.email         = ["bbdurand@gmail.com"]
+
+  spec.summary       = %q{Use capistrano to deploy docker based applications.}
+  spec.homepage      = "https://github.com/bdurand/capistrano-docker_cluster"
+  spec.license       = "MIT"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  ignore_files = %w(
+    .gitignore
+    .travis.yml
+    Appraisals
+    Gemfile
+    Gemfile.lock
+    Rakefile
+    gemfiles/
+    spec/
+  )
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject{ |f| ignore_files.any?{ |path| f.start_with?(path) } }
+  end
+  spec.bindir        = "bin"
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = '>= 2.2.2'
+
+  spec.add_dependency "capistrano", "~> 3.7"
+  spec.add_dependency "capistrano-scm-none", "~> 0.1"
+  spec.add_development_dependency "rake"
+end

data/lib/capistrano/docker_cluster.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'capistrano/scm/none'
+
+require_relative "docker_cluster/version"
+require_relative "docker_cluster/scripts"
+
+load File.expand_path("tasks/docker_cluster.rake", __dir__)
+
+install_plugin Capistrano::Scm::None::Plugin

data/lib/capistrano/docker_cluster/scripts.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Capistrano
+  module DockerCluster
+    class Scripts
+      def initialize(context)
+        @context = context
+      end
+
+      # Build a custom command line start script with the configuration arguments for
+      # each docker application on the host. This allows each app to be started with
+      # the predefined configuration by calling `bin/start app`.
+      def start_script(host)
+        apps = Array(fetch_for_host(host, :docker_apps))
+        cmd = "exec bin/docker-cluster"
+        image_id = fetch(:docker_image_id)
+        prefix = fetch(:docker_prefix)
+
+        cases = []
+        apps.each do |app|
+          args = app_host_args(app, host)
+          cases << "  '#{app}')\n    #{cmd} #{args.join(' ')} --name '#{prefix}#{app}' --image '#{image_id}' \"$@\"\n    ;;"
+        end
+
+        <<~BASH
+          #!/usr/bin/env bash
+
+          # Generated: #{Time.now.utc.iso8601}
+          # Docker image tag: #{fetch(:docker_repository)}/#{fetch(:docker_tag)}
+
+          set -o errexit
+
+          cd $(dirname $0)/..
+
+          typeset app=$1
+          shift
+
+          case $app in
+          #{cases.join("\n")}
+            *)
+              >&2 echo "Usage: $0 #{apps.join('|')}"
+              exit 1
+          esac
+        BASH
+      end
+
+      # Build a custom command line run script with the configuration arguments for
+      # each docker application on the host to run one off containers.
+      def run_script(host)
+        # For the run script, all configured apps are included, not just the deployed ones.
+        # This allows configuring, for example, a "console" app to open up a console in a container.
+        apps = Array(fetch_for_host(host, :docker_apps))
+        app_configs = fetch_for_host(host, :docker_app_configs)
+        apps.concat(app_configs.keys) if app_configs.is_a?(Hash)
+        app_args = fetch_for_host(host, :docker_app_args)
+        apps.concat(app_args.keys) if app_args.is_a?(Hash)
+        apps = apps.collect(&:to_s).uniq
+
+        cmd = "exec bin/docker-cluster"
+        image_id = fetch(:docker_image_id)
+
+        cases = []
+        apps.each do |app|
+          args = app_host_args(app, host)
+          cases << "  '#{app}')\n    #{cmd} #{args.join(' ')} --image '#{image_id}' --one-off \"$@\"\n    ;;"
+        end
+
+        <<~BASH
+          #!/usr/bin/env bash
+
+          # Generated: #{Time.now.utc.iso8601}
+          # Docker image tag: #{fetch(:docker_repository)}/#{fetch(:docker_tag)}
+
+          set -o errexit
+
+          cd $(dirname $0)/..
+
+          typeset app=$1
+          shift
+
+          case $app in
+          #{cases.join("\n")}
+            *)
+              >&2 echo "Usage: $0 #{apps.join('|')}"
+              exit 1
+          esac
+        BASH
+      end
+
+      # Build a custom command line stop script for each docker application on the host.
+      def stop_script(host)
+        apps = Array(fetch_for_host(host, :docker_apps))
+        prefix = fetch(:docker_prefix)
+
+        cases = []
+        all = []
+        apps.each do |app|
+          cases << "  '#{app}')\n    exec bin/docker-cluster --name '#{prefix}#{app}' --count 0\n    ;;"
+        end
+
+        <<~BASH
+          #!/usr/bin/env bash
+
+          # Generated: #{Time.now.utc.iso8601}
+          # Docker image tag: #{fetch(:docker_repository)}/#{fetch(:docker_tag)}
+
+          set -o errexit
+
+          cd $(dirname $0)/..
+
+          typeset app=$1
+
+          case $app in
+          #{cases.join("\n")}
+            *)
+              >&2 echo "Usage: $0 #{apps.join('|')}"
+              exit 1
+          esac
+        BASH
+      end
+
+      # Returns a list of all local configuration file paths that need to be uploaded to
+      # the host.
+      def docker_config_map(host)
+        configs = {}
+        Array(fetch(:docker_configs)).each do |path|
+          configs[File.basename(path)] = path
+        end
+
+        apps = Array(fetch_for_host(host, :docker_apps))
+
+        app_configs = app_configuration(fetch(:docker_app_configs, nil))
+        apps.each do |app|
+          Array(app_configs[app.to_s]).each do |path|
+            configs[File.basename(path)] = path
+          end
+        end
+
+        Array(host.properties.docker_configs).each do |path|
+          configs[File.basename(path)] = path
+        end
+
+        host_app_configs = app_configuration(host.properties.send(:docker_app_configs))
+        apps.each do |app|
+          Array(host_app_configs[app.to_s]).each do |path|
+            configs[File.basename(path)] = path
+          end
+        end
+
+        configs
+      end
+
+      # Fetch a host specific property. If a the value is not defined as host specific,
+      # then fallback to the globally defined property.
+      def fetch_for_host(host, property, default = nil)
+        host.properties.send(property) || fetch(property, default)
+      end
+
+      private
+
+      # Helper to fetch a property defined in the capistrano script.
+      def fetch(property, default = nil)
+        @context.fetch(property, default)
+      end
+
+      # Helper to normalize used to multiple configurations keyed by the app name
+      # to ensure that the keys are all strings.
+      def app_configuration(hash)
+        hash ||= {}
+        config = {}
+        hash.each do |key, value|
+          config[key.to_s] = value
+        end
+        config
+      end
+
+      # Translate a list of config file paths into command line arguments for the docker_clusther.sh command.
+      def config_args(config_files)
+        Array(config_files).collect{ |path| "--config 'config/#{File.basename(path)}'" }
+      end
+
+      def app_host_args(app, host)
+        config_args = config_args(fetch(:docker_configs, nil))
+        command_args = Array(fetch(:docker_args, nil))
+
+        host_config_args = config_args(host.properties.send(:docker_configs))
+        host_command_args = Array(host.properties.send(:"docker_args"))
+
+        app_configs = app_configuration(fetch(:docker_app_configs, {}))
+        app_args = app_configuration(fetch(:docker_app_args, {}))
+
+        host_app_configs = app_configuration(host.properties.send(:"docker_app_configs"))
+        host_app_args = app_configuration(host.properties.send(:"docker_app_args"))
+
+        app = app.to_s
+        app_config_args = config_args(app_configs[app])
+        app_command_args = Array(app_args[app])
+        host_app_config_args = config_args(host_app_configs[app])
+        host_app_command_args = Array(host_app_args[app])
+        args = config_args + command_args + app_config_args + app_command_args + host_config_args + host_command_args + host_app_config_args + host_app_command_args
+        args.uniq
+      end
+    end
+  end
+end

data/lib/capistrano/docker_cluster/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module DockerCluster
+    VERSION = "1.0.1"
+  end
+end

data/lib/capistrano/tasks/docker_cluster.rake

@@ -0,0 +1,144 @@
+# frozen_string_literal: true
+
+set :docker_roles, [:docker]
+
+def as_docker_user
+  user = fetch(:docker_user, nil)
+  if user
+    as(user) do
+      with(fetch(:docker_env, {})) do
+        yield
+      end
+    end
+  else
+    yield
+  end
+end
+
+namespace :deploy do
+  after :new_release_path, "docker:create_release"
+  after :updating, "docker:update"
+  after :published, "docker:restart"
+
+  task :upload do
+  end
+end
+
+namespace :docker do
+  desc "create the docker release directory and pull the image if necessary"
+  task :create_release do
+    on release_roles(fetch(:docker_roles)) do
+      execute :mkdir, "-p", release_path
+    end
+
+    if fetch(:docker_repository).include?("/")
+       invoke "docker:pull"
+    end
+  end
+
+  task :set_image_id => :build do
+    on release_roles(fetch(:docker_roles)).first do
+      docker_tag_url =  "#{fetch(:docker_repository)}:#{fetch(:docker_tag)}"
+      as_docker_user do
+        image_id = capture(:docker, "image", "ls", "--no-trunc", "--format", "'{{.ID}}'", docker_tag_url)
+        set :docker_image_id, image_id[7, 12]
+      end
+    end
+  end
+
+  desc "Build and tag the docker image. This task does nothing by default, but can be implemented where needed."
+  task :build do
+  end
+
+  desc "Update the configuration and command line arguments for running a docker deployment."
+  task :update => :set_image_id do
+    invoke("docker:copy_configs")
+    invoke("docker:upload_commands")
+  end
+
+  desc "Prune the docker engine of all dangling images, containers, and volumes."
+  task :prune do
+    on release_roles(fetch(:docker_roles)) do |host|
+      as_docker_user do
+        execute :docker, "system", "prune", "--force"
+      end
+    end
+  end
+
+  desc "Pull a tag from a remote into the local docker engine. If the task docker:authenticate is defined, it will be invoked first."
+  task :pull do
+    docker_tag_url =  "#{fetch(:docker_repository)}:#{fetch(:docker_tag)}"
+    if Rake::Task.task_defined?('docker:authenticate')
+      invoke "docker:authenticate"
+    end
+    on release_roles(fetch(:docker_roles)) do |host|
+      as_docker_user do
+        execute :docker, "pull", docker_tag_url
+      end
+    end
+  end
+
+  desc "Restart the docker containers (alias to docker:start)."
+  task :restart do
+    invoke("docker:start")
+  end
+
+  desc "Restart the docker containers."
+  task :start do
+    on release_roles(fetch(:docker_roles)) do |host|
+      within "#{fetch(:deploy_to)}/current" do
+        scripts = Capistrano::DockerCluster::Scripts.new(self)
+        Array(scripts.fetch_for_host(host, :docker_apps)).each do |app|
+          as_docker_user do
+            execute "bin/start", app
+          end
+        end
+      end
+    end
+  end
+
+  desc "Stop the docker containers."
+  task :stop do
+    on release_roles(fetch(:docker_roles)) do |host|
+      within "#{fetch(:deploy_to)}/current" do
+        scripts = Capistrano::DockerCluster::Scripts.new(self)
+        Array(scripts.fetch_for_host(host, :docker_apps)).each do |app|
+          as_docker_user do
+            execute "bin/stop", app
+          end
+        end
+      end
+    end
+  end
+
+  desc "Upload the commands to stop and start the application docker containers."
+  task :upload_commands do
+    on release_roles(fetch(:docker_roles)) do |host|
+      within fetch(:release_path) do
+        execute(:mkdir, "-p", "bin")
+        scripts = Capistrano::DockerCluster::Scripts.new(self)
+        docker_cluster_path = File.join(__dir__, "..", "..", "..", "bin", "docker-cluster")
+        upload! docker_cluster_path, "bin/docker-cluster"
+        upload! StringIO.new(scripts.start_script(host)), "bin/start"
+        upload! StringIO.new(scripts.stop_script(host)), "bin/stop"
+        upload! StringIO.new(scripts.run_script(host)), "bin/run"
+        execute :chmod, "a+x", "bin/*"
+      end
+    end
+  end
+
+  desc "Copy configuration files used to start the docker containers."
+  task :copy_configs do
+    on release_roles(fetch(:docker_roles)) do |host|
+      configs = Capistrano::DockerCluster::Scripts.new(self).docker_config_map(host)
+      unless configs.empty?
+        within fetch(:release_path) do
+          execute(:mkdir, "-p", "config")
+          configs.each do |name, local_path|
+            upload! local_path, "config/#{name}"
+          end
+        end
+      end
+    end
+  end
+end

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: capistrano-docker_cluster
+version: !ruby/object:Gem::Version
+  version: 1.0.1
+platform: ruby
+authors:
+- Brian Durand
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-03-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: capistrano
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.7'
+- !ruby/object:Gem::Dependency
+  name: capistrano-scm-none
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- bbdurand@gmail.com
+executables:
+- docker-cluster
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGE_LOG.md
+- MIT_LICENSE.txt
+- README.md
+- bin/docker-cluster
+- capistrano-docker_cluster.gemspec
+- lib/capistrano/docker_cluster.rb
+- lib/capistrano/docker_cluster/scripts.rb
+- lib/capistrano/docker_cluster/version.rb
+- lib/capistrano/tasks/docker_cluster.rake
+homepage: https://github.com/bdurand/capistrano-docker_cluster
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Use capistrano to deploy docker based applications.
+test_files: []