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.

• 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 remove config/database.yml and config/secrets.yml if present. Both of these will be provided by environment variables.
• For :linked_dirs remove tmp/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 to PUMA_MAX_THREAD and RAILS_MIN_THREAD to PUMA_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