diff --git a/CHANGELOG.md b/CHANGELOG.md index dcba36a..724a3d8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Added + +- `:solid_queue_service_unit_env_vars` and `:solid_queue_service_unit_env_files` add `Environment=` and `EnvironmentFile=` lines to the systemd service. They default to `:service_unit_env_vars` and `:service_unit_env_files`, as in capistrano3-puma and capistrano-sidekiq ([#13](https://github.com/codeur/capistrano-solid_queue/pull/13), from [#6](https://github.com/codeur/capistrano-solid_queue/pull/6) by [@floriancrusius](https://github.com/floriancrusius)). +- A Configuration section in the README ([#13](https://github.com/codeur/capistrano-solid_queue/pull/13)). + +### Changed + +- In `:system` mode, the service runs as the user Capistrano connects with instead of root. Run `cap solid_queue:install` again, then give that user back the files the service may have created as root ([#13](https://github.com/codeur/capistrano-solid_queue/pull/13), from [#6](https://github.com/codeur/capistrano-solid_queue/pull/6) by [@floriancrusius](https://github.com/floriancrusius)). +- The service description names the application and the stage ([#13](https://github.com/codeur/capistrano-solid_queue/pull/13)). + ## [0.1.3] - 2026-11-09 ### Fixed diff --git a/README.md b/README.md index 42a7336..41bc709 100644 --- a/README.md +++ b/README.md @@ -70,6 +70,49 @@ through their Capistrano counterparts, ex: `bundle exec cap solid_queue:restart` The plugin has registered a Capistrano `hook` to run `bundle exec cap solid_queue:restart` after deploy. See [`#register_hooks`](lib/capistrano/solid_queue.rb) +## Configuration + +These variables can be set in `config/deploy.rb` or in a stage file. The values below are the defaults. + +```ruby +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 solid_queue:install` again: deploys don't regenerate the service. + +### User or system 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: + +```ruby +set :solid_queue_systemctl_user, :system +``` + +The 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. + +### Environment + +The service gets these variables, in this order: + +1. `RAILS_ENV`, from `:rails_env`, or from `:stage` when `:rails_env` isn't set. +2. Capistrano's `default_env`, except `PATH`. Each value is expanded by the server shell, as in Capistrano commands (`$HOME`…). +3. `MALLOC_ARENA_MAX=2`. +4. `:solid_queue_service_unit_env_vars`, written as is in `Environment="…"` 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 `-`. + +```ruby +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. + ## Development 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. diff --git a/lib/capistrano/solid_queue.rb b/lib/capistrano/solid_queue.rb index cf190b3..9301427 100644 --- a/lib/capistrano/solid_queue.rb +++ b/lib/capistrano/solid_queue.rb @@ -11,6 +11,8 @@ def set_defaults set_if_empty :solid_queue_error_log, -> { File.join(shared_path, "log", "solid_queue.log") } set_if_empty :solid_queue_service_unit_name, -> { "#{fetch(:application)}_solid_queue_#{fetch(:stage)}" } set_if_empty :solid_queue_systemd_conf_dir, -> { fetch_systemd_unit_path } + set_if_empty :solid_queue_service_unit_env_vars, -> { fetch(:service_unit_env_vars, []) } + set_if_empty :solid_queue_service_unit_env_files, -> { fetch(:service_unit_env_files, []) } end def define_tasks diff --git a/lib/capistrano/templates/solid_queue.service.erb b/lib/capistrano/templates/solid_queue.service.erb index b2cf7ca..a002793 100644 --- a/lib/capistrano/templates/solid_queue.service.erb +++ b/lib/capistrano/templates/solid_queue.service.erb @@ -1,9 +1,12 @@ [Unit] -Description=SolidQueue background job +Description=SolidQueue background job for <%= fetch(:application) %> (<%= fetch(:stage) %>) After=syslog.target network.target [Service] Type=simple +<% if fetch(:solid_queue_systemctl_user) == :system -%> +User=<%= capture(:id, "-un") %> +<% end -%> Environment='RAILS_ENV=<%= fetch(:rails_env, fetch(:stage)) %>' <% fetch(:default_env).reject{ |k, _| k.to_s == 'path' }.each do |variable, value| -%> Environment='<%= variable.to_s.upcase %>=<%= capture(:printf, "%s", %("#{value.to_s.gsub('"', '\"')}")) %>' @@ -13,6 +16,12 @@ ExecStart=<%= capture(:echo, SSHKit.config.command_map[:bundle]).strip %> exec r ExecReload=/bin/kill -TSTP $MAINPID ExecStop=/bin/kill -TERM $MAINPID Environment=MALLOC_ARENA_MAX=2 +<% fetch(:solid_queue_service_unit_env_vars).each do |variable| -%> +Environment="<%= variable %>" +<% end -%> +<% fetch(:solid_queue_service_unit_env_files).each do |file| -%> +EnvironmentFile=<%= file %> +<% end -%> # if we crash, restart RestartSec=1 diff --git a/test/capistrano/test_service_unit.rb b/test/capistrano/test_service_unit.rb index 41ccb8c..f79994c 100644 --- a/test/capistrano/test_service_unit.rb +++ b/test/capistrano/test_service_unit.rb @@ -1,10 +1,47 @@ # frozen_string_literal: true require "test_helper" +require "etc" class Capistrano::TestServiceUnit < Minitest::Test include CapistranoProject + def test_description_names_application_and_stage + assert_includes generate_unit, "Description=SolidQueue background job for app (preprod)\n" + end + + def test_system_service_runs_as_the_capistrano_user + unit = generate_unit(stage_config: "set :solid_queue_systemctl_user, :system") + + assert_includes unit, "User=#{Etc.getpwuid.name}\n" + end + + def test_user_service_has_no_user_line + refute_match(/^User=/, generate_unit) + end + + def test_service_unit_env_vars_and_files + unit = generate_unit(stage_config: <<~RUBY) + set :solid_queue_service_unit_env_vars, ["MALLOC_ARENA_MAX=4", "GREETING=two words"] + set :solid_queue_service_unit_env_files, ["/var/www/app/shared/.env", "-/etc/default/app"] + RUBY + + assert_includes unit, %(Environment="GREETING=two words"\n) + assert_includes unit, "EnvironmentFile=/var/www/app/shared/.env\n" + assert_includes unit, "EnvironmentFile=-/etc/default/app\n" + assert_operator unit.index("Environment=MALLOC_ARENA_MAX=2\n"), :<, unit.index(%(Environment="MALLOC_ARENA_MAX=4"\n)) + end + + def test_service_unit_env_defaults_to_shared_settings + unit = generate_unit(stage_config: <<~RUBY) + set :service_unit_env_vars, ["FOO=bar"] + set :service_unit_env_files, ["/etc/app.env"] + RUBY + + assert_includes unit, %(Environment="FOO=bar"\n) + assert_includes unit, "EnvironmentFile=/etc/app.env\n" + end + def test_rails_env_is_capistrano_rails_env unit = generate_unit(stage_config: 'set :rails_env, "production"')