dlss-capistrano-docker
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.
Included Tasks
-
ssh
: establishes an SSH connection to the host running in environment, and changes into the current deployment directory. -
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
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
.
Usage
For an example of any of the following, see https://github.com/sul-dlss/happy-heron
Gemfile
- 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.)
Capfile
- 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
config/deploy.rb
- 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.
config/deploy/<environment>.rb
- 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.
config/puma.rb
- 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!
.
config/schedule.rb
- Add
set :job_template, nil
to execute with sh instead of bash.
Dockerfile
- 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.
docker-compose.prod.yml
- 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
.dockerignore
Ignore public.assets