Capistrano::Docker::Compose

Docker Compose specific tasks for Capistrano allowing seamless zero downtime containerised deployments.

Minimum requirements

Capistrano 3.5
Docker Engine 1.11
Docker Compose 1.7
HAProxy 1.6

Supported databases

Database	Versions tested
PostgreSQL	9.5
MariaDB	5.5, 10.1

Installation

Add this line to your application's Gemfile:

gem 'capistrano-docker-compose'

And then execute:

$ bundle

Or install it yourself as:

$ gem install capistrano-docker-compose

Usage

Create Docker Compose descriptors for each environment leaving docker-compose.yml as default for development environment, e.g.:

docker-compose.yml
docker-compose-staging.yml
docker-compose-production.yml

Make Compose YAML with web service (name is conventional) using following environment variables:

CAP_DOCKER_COMPOSE_ROOT_PATH for shared path
CAP_DOCKER_COMPOSE_PORT for port range

If you're using database service with migrations in Ruby on Rails, make sure to name database service as db (name is conventional). See also Compose YAML example.

Add capistrano-docker-compose to Capfile:

# Capfile
require 'capistrano/docker/compose'

Configure following Docker Compose specific options in config/deploy.rb and/or config/deploy/<environment>.rb:

# Define port range in respect to load balancer on server
# If 2 or more environments reside on same server, configure port range as per environment
# Ruby's Range object is expected, see http://ruby-doc.org/core-2.3.0/Range.html
# Example: set :docker_compose_port_range, 2070..2071
set :docker_compose_port_range, <port>..<port>

# OPTIONAL
# User name when running the Docker image (reflecting Docker's USER instruction)
# Example: set :docker_compose_user, 'pioneer'
set :docker_compose_user, '<username>'

# OPTIONAL
# Roles considered
# Defaults to :all
# Example: set :docker_compose_roles, :web
set :docker_compose_roles, <roles>

Configure HAProxy load balancer with port range defined in docker_compose_port_range, see example configuration.

NB! Ensure load balancer's HTTP health check uses Layer 7 and corresponds to the needs of the particular application.

PHP projects

To use capistrano-docker-compose on PHP project, such as Wordpress or Drupal:

Add Gemfile to project root:

# Gemfile
source 'https://rubygems.org'

group :capistrano do
    gem 'capistrano-bundler'
    gem 'capistrano-docker-compose'
end

Run bundle to install

If bundling is not desired during deployment (no RubyGems dependencies), Capistrano flow can be altered by removing bundler task:

# config/deploy.rb
namespace :deploy do
  Rake::Task["bundler:install"].clear_actions
end

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/interactive-pioneers/capistrano-docker-compose. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.