This gem provides Capistrano Docker deployment tasks used by Stanford Libraries' Digital Library Systems and Services group.
It requires that the services to be run on a server be specified by a docker compose configuration file.
ssh
: establishes an SSH connection to the host running in environment, and changes into the current deployment directory.ssh_check
: establishes an SSH connection to all app servers running prints environment information to confirm the connection was made. (This is used by sdr-deploy to check SSH connections can be made in bulk before proceeding with a mass deploy.)honeybadger:notify
: notifies Honeybadger of deploy using curl (thus, ruby is not required on host).docker:login
: log into Docker Hub. Logging in is required to avoid strict image download limits.docker:logout
: log out of Docker Hub.docker:prune
: prune docker artifacts to avoid filling disk space.docker_compose:migrate
: migrate the database.docker_compose:seed
: seed the database.docker_compose:build
: build images for the services.docker_compose:setup_rabbit
: create channel, queues, etc for RabbitMQ.docker_compose:restart
: down then up services.docker_compose:up
: start services.docker_compose:down
: tear down services.docker_compose:copy_assets
: copy assets from a container to the server so they can be served by Apache.docker_compose:dereference_linked_files
: turn linked files into actual files.docker_compose:dereference_linked_dirs
: turn linked directories into actual directories containing actual files.
Hooks into the Capistrano lifecycle are provided for most of these tasks. These hooks can be controlled with variables, e.g., docker_hub_use_hooks
to control the hooks for docker:login
and docker:logout
.
In addition to tasks included in this gem, a hook is provided for shared_configs:update
.
For an example of any of the following, see https://github.com/sul-dlss/happy-heron
- Add
gem 'dlss-capistrano-docker', require: false
to the deployment group. - Remove any gems that are removed from
Capfile
below. - Move puma gem from development/test dependencies to the application dependencies. (Puma will be used as the application server instead of Passenger.)
- Remove any of the following:
require 'capistrano/bundler'
require 'capistrano/rails'
require 'capistrano/honeybadger'
require 'capistrano/passenger'
require 'whenever/capistrano'
require 'dlss/capistrano'
- Add
require 'dlss/docker/capistrano
- For
:linked_files
removeconfig/database.yml
andconfig/secrets.yml
if present. Both of these will be provided by environment variables. - For
:linked_dirs
removetmp/pids
,tmp/cache
,tmp/sockets
if present.log
,config/settings
, and,public/system
should remain. (public/system
is necessary for Capistrano::Maintenance.) - Remove any sidekiq, sneakers, passenger, whenever, or shared_configs related settings.
- Add
set :docker_compose_file, 'docker-compose.prod.yml'
to reference the production docker-compose file. - Optionally, add
set :docker_compose_seed_use_hooks, true
to perform seeding. - Optionally, add
set :docker_compose_rabbitmq_use_hooks, true
to perform Rabbitmq setup. - Note that there are other settings supported by this gem for additional configuration.
- Each server should have the
app
role and any roles that correspond with profiles in the docker-compose file. This is what controls what services are run on the server.
- Change
RAILS_MAX_THREAD
toPUMA_MAX_THREAD
andRAILS_MIN_THREAD
toPUMA_MIN_THREAD
. - Enable workers with
workers ENV.fetch('PUMA_WORKERS', 2)
- Enable preload with
preload_app!
.
- Add
set :job_template, nil
to execute with sh instead of bash.
- When possible, base the image on Alpine (e.g.,
FROM ruby:3.1-alpine
). - Processes should run as the application user (e.g.,
h2
) not root, with user id and group id set to match the server. - If using Whenever, install Supercronic (which does not have to run as root) and write the crontab file during the build with
RUN sh -c 'bundle exec whenever . | tee -a config/crontab'
. - When possible, write to both a log file and stdout.
- Precompile assets (
RUN bin/rails assets:precompile
) as part of the build.SECRET_KEY_BASE
will need to be available for precompiling.
- Duplicate configuration can be shared with fragments (e.g.,
&environment
/*environment
). - The command for a container can be overridden with
command:
, e.g.,command: bin/bundle exec rake sneakers:run 2>&1 | tee -a log/sneakers.log
. - Each service should be assigned to one or more profiles. These correspond to capistrano roles. For example:
profiles:
- cron
- Containers should link in the shared logs directory. For example:
volumes:
- /opt/app/h2/happy-heron/shared/log:/app/log
- Environment variables provided by the server should be passed through to the container. For example:
environment:
- HONEYBADGER_API_KEY
Ignore public.assets