Runs Solid Queue in its own process, with bin/jobs, as a systemd service. The application needs bin/jobs: Rails 8 applications have it, and bin/rails solid_queue:install creates it. If Solid Queue runs inside Puma with its plugin (plugin :solid_queue), you don't need this gem: both would start a Solid Queue supervisor.
Adds the following capistrano commands:
cap solid_queue:disable # Disable solid_queue systemd service
cap solid_queue:enable # Enable solid_queue systemd service
cap solid_queue:generate # Generate solid_queue systemd service
cap solid_queue:install # Install solid_queue systemd service
cap solid_queue:restart # Restart solid_queue service via systemd
cap solid_queue:start # Start solid_queue service via systemd
cap solid_queue:status # Get solid_queue service status via systemd
cap solid_queue:stop # Stop solid_queue service via systemd
cap solid_queue:uninstall # Uninstall solid_queue systemd serviceAdd this line to your application's Gemfile:
group :development do
gem 'capistrano-solid_queue', require: false
endAnd then execute:
$ bundle
# Capfile
require 'capistrano/solid_queue'
install_plugin Capistrano::SolidQueue::SystemdTo prevent loading the hooks of the plugin, add false to the load_hooks param.
# Capfile
install_plugin Capistrano::SolidQueue::Systemd, load_hooks: falseThen run once
bundle exec cap production solid_queue:installfor the initial setup. This will copy a systemd service definition to ~/.config/systemd/user/<application>_solid_queue_<stage>.service on your server marked with Capistrano role db.
It will also enable it in systemd, so that you can then run commands such as:
systemctl --user status your_app_solid_queue_production
systemctl --user start your_app_solid_queue_production
systemctl --user stop your_app_solid_queue_production
systemctl --user restart your_app_solid_queue_productionthrough their Capistrano counterparts, ex: bundle exec cap production solid_queue:restart.
A user service only runs while its user has a session open on the server, unless lingering is enabled for that user. Enable it once on each server, with the user Capistrano connects with:
sudo loginctl enable-linger deployThe plugin registers these Capistrano hooks:
- after
deploy:updated,solid_queue:stopstops the service; - after
deploy:published,solid_queue:startstarts the service on the new release; - after
deploy:failed,solid_queue:restartrestarts the service.
See #register_hooks
These variables can be set in config/deploy.rb or in a stage file. The values below are the defaults.
set :solid_queue_role, "db"
set :solid_queue_access_log, -> { File.join(shared_path, "log", "solid_queue.log") }
set :solid_queue_error_log, -> { File.join(shared_path, "log", "solid_queue.log") }
set :solid_queue_service_unit_name, -> { "#{fetch(:application)}_solid_queue_#{fetch(:stage)}" }
set :solid_queue_service_unit_env_vars, -> { fetch(:service_unit_env_vars, []) }
set :solid_queue_service_unit_env_files, -> { fetch(:service_unit_env_files, []) }After changing any of them, run cap <stage> solid_queue:install again: deploys don't regenerate the service.
By default, Solid Queue runs as a user service: systemctl --user, with the unit file in ~/.config/systemd/user. To run it as a system service instead:
set :solid_queue_systemctl_user, :systemThe unit file then goes to /etc/systemd/system/, systemctl runs through sudo, and the service runs as the user Capistrano connects with. :solid_queue_systemd_conf_dir sets another directory for the unit file.
The service gets these variables, in this order:
RAILS_ENV, from:rails_env, or from:stagewhen:rails_envisn't set.- Capistrano's
default_env, exceptPATH. Each value is expanded by the server shell, as in Capistrano commands ($HOME…). MALLOC_ARENA_MAX=2.:solid_queue_service_unit_env_vars, written as is inEnvironment="…"lines.
A later line overrides an earlier one, so :solid_queue_service_unit_env_vars can override any of the above. The files of :solid_queue_service_unit_env_files (EnvironmentFile= lines) override all of them. systemd doesn't start the service when one of these files is missing, unless its path starts with -.
set :solid_queue_service_unit_env_vars, ["MALLOC_ARENA_MAX=4"]
set :solid_queue_service_unit_env_files, ["/var/www/my_app/shared/.env", "-/etc/default/my_app"]When they aren't set, the :service_unit_env_vars and :service_unit_env_files variables, also read by capistrano3-puma and capistrano-sidekiq, are used.
Solid Queue reads the options of bin/jobs from environment variables too, for instance:
set :solid_queue_service_unit_env_vars, ["SOLID_QUEUE_CONFIG=config/calendar.yml", "SOLID_QUEUE_SKIP_RECURRING=true"]After checking out the repo, run bin/setup to install dependencies. Then, run rake test to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and the created tag, and push the .gem file to rubygems.org.
Bug reports and pull requests are welcome on GitHub at https://github.com/codeur/capistrano-solid_queue.
The gem is available as open source under the terms of the MIT License.
Everyone interacting in the Capistrano::SolidQueue project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct.
The structure and code of the gem are heavily inspired by capistrano-good_job's systemd tasks
and (How I) Deploy Solid Queue with Capistrano article from Rob Zolkos.