Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <stage> 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
Expand Down
43 changes: 43 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 <stage> 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.
Expand Down
2 changes: 2 additions & 0 deletions lib/capistrano/solid_queue.rb
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
11 changes: 10 additions & 1 deletion lib/capistrano/templates/solid_queue.service.erb
Original file line number Diff line number Diff line change
@@ -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('"', '\"')}")) %>'
Expand All @@ -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
Expand Down
37 changes: 37 additions & 0 deletions test/capistrano/test_service_unit.rb
Original file line number Diff line number Diff line change
@@ -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"')

Expand Down
Loading