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
2 changes: 1 addition & 1 deletion .standard.yml
Original file line number Diff line number Diff line change
@@ -1,3 +1,3 @@
# For available configuration options, see:
# https://github.com/standardrb/standard
ruby_version: 2.6
ruby_version: 3.1
16 changes: 16 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,22 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).

- 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)).
- Deploys no longer run `solid_queue:quiet` after `deploy:starting`. Solid Queue has no quiet mode: the `SIGTERM` it sends starts a shutdown, so jobs stopped for the whole deploy. The service is now stopped after `deploy:updated` and started after `deploy:published` ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- Ruby 3.1 or later is required ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- Capistrano 3.5 or later is required: `Capistrano::Plugin` doesn't exist before ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).

### Removed

- `solid_queue:reload` and the `ExecReload=` line of the service: the `SIGTSTP` it sent didn't reload Solid Queue ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).

### Fixed

- In `:system` mode, `solid_queue:install` and `solid_queue:uninstall` work when Capistrano doesn't connect as root: the unit is uploaded to `:tmp_dir`, then moved and removed with `sudo` ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- `solid_queue:install` enables the service on each server right after uploading its unit there, instead of running `solid_queue:enable` on every server from the first one ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- `solid_queue:uninstall` removes only the unit of the service, not every file whose name starts with it ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- `solid_queue:status` shows the status of a stopped service instead of failing ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- The README lists the hooks the plugin registers ([#14](https://github.com/codeur/capistrano-solid_queue/pull/14)), tells to enable lingering for user services, and links to the right code of conduct ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).
- The gem's changelog link points to this file, and the gem no longer ships its outdated RBS signature, `.standard.yml` and `Rakefile` ([#15](https://github.com/codeur/capistrano-solid_queue/pull/15)).

## [0.1.3] - 2026-11-09

Expand Down
35 changes: 19 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -3,17 +3,16 @@
Adds the following capistrano commands:

```sh
solid_queue:generate # Generate locally solid_queue systemd service unit file
solid_queue:disable # Disable solid_queue systemd service
solid_queue:enable # Enable solid_queue systemd service
solid_queue:install # Install solid_queue systemd service
solid_queue:reload # Reload solid_queue service via systemd
solid_queue:quiet # Quiet solid_queue service via systemd
solid_queue:restart # Restart solid_queue service via systemd
solid_queue:start # Start solid_queue service via systemd
solid_queue:status # Get solid_queue service status via systemd
solid_queue:stop # Stop solid_queue service via systemd
solid_queue:uninstall # Uninstall solid_queue systemd service
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:quiet # Quiet solid_queue (start graceful termination)
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 service
```


Expand Down Expand Up @@ -53,23 +52,27 @@ bundle exec cap production solid_queue:install

for the initial setup. This will copy a [`systemd` service definition](lib/capistrano/templates/solid_queue.service.erb) to `~/.config/systemd/user/<application>_solid_queue_<stage>.service` on your server marked with Capistrano role `db`.

It will also `enable` it in `systemd`, allowing to to then run commands such as:
It will also `enable` it in `systemd`, so that you can then run commands such as:

```sh
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 reload your_app_solid_queue_production
systemctl --user restart your_app_solid_queue_production
```

through their Capistrano counterparts, ex: `bundle exec cap solid_queue:restart`.
through 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:

```sh
sudo loginctl enable-linger deploy
```

## Usage

The plugin registers these Capistrano hooks:

- after `deploy:starting`, `solid_queue:quiet` sends `SIGTERM` to the service, so Solid Queue starts a graceful shutdown;
- after `deploy:updated`, `solid_queue:stop` stops the service;
- after `deploy:published`, `solid_queue:start` starts the service on the new release;
- after `deploy:failed`, `solid_queue:restart` restarts the service.
Expand Down Expand Up @@ -135,7 +138,7 @@ The gem is available as open source under the terms of the [MIT License](https:/

## Code of Conduct

Everyone interacting in the Capistrano::SolidQueue project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/capistrano-solid_queue/blob/main/CODE_OF_CONDUCT.md).
Everyone interacting in the Capistrano::SolidQueue project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/codeur/capistrano-solid_queue/blob/main/CODE_OF_CONDUCT.md).

## Credits

Expand Down
14 changes: 6 additions & 8 deletions capistrano-solid_queue.gemspec
Original file line number Diff line number Diff line change
Expand Up @@ -8,29 +8,27 @@ Gem::Specification.new do |spec|
spec.authors = ["Brice TEXIER"]
spec.email = ["brice@codeur.com"]

spec.summary = "Adds support for SolidQueue to Capistrano 3.x"
spec.description = "Adds support for SolidQueue to Capistrano 3.x"
spec.summary = "Run Solid Queue as a systemd service with Capistrano"
spec.description = "Capistrano tasks and deploy hooks that install, start, stop and restart Solid Queue as a systemd service."
spec.homepage = "https://github.com/codeur/capistrano-solid_queue"
spec.license = "MIT"
spec.required_ruby_version = ">= 2.6.0"
spec.required_ruby_version = ">= 3.1.0"

spec.metadata["allowed_push_host"] = "https://rubygems.org"

spec.metadata["homepage_uri"] = spec.homepage
spec.metadata["source_code_uri"] = "https://github.com/codeur/capistrano-solid_queue"
spec.metadata["changelog_uri"] = "https://github.com/codeur/capistrano-solid_queue/releases"
spec.metadata["changelog_uri"] = "https://github.com/codeur/capistrano-solid_queue/blob/main/CHANGELOG.md"

# Specify which files should be added to the gem when it is released.
# The `git ls-files -z` loads the files in the RubyGem that have been added into git.
spec.files = Dir.chdir(__dir__) do
`git ls-files -z`.split("\x0").reject do |f|
(File.expand_path(f) == __FILE__) ||
f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
f.start_with?(*%w[bin/ test/ spec/ features/ .git .github .standard.yml appveyor Gemfile Rakefile])
end
end
spec.bindir = "exe"
spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
spec.require_paths = ["lib"]

spec.add_dependency "capistrano", ">= 3.0"
spec.add_dependency "capistrano", ">= 3.5"
end
9 changes: 8 additions & 1 deletion lib/capistrano/solid_queue.rb
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,19 @@ def define_tasks
end

def register_hooks
after "deploy:starting", "solid_queue:quiet"
after "deploy:updated", "solid_queue:stop"
after "deploy:published", "solid_queue:start"
after "deploy:failed", "solid_queue:restart"
end

def service_unit(context)
ERB.new(File.read(File.expand_path("templates/solid_queue.service.erb", __dir__)), trim_mode: "-").result(context)
end

def service_unit_file
"#{fetch(:solid_queue_service_unit_name)}.service"
end

def execute_systemd(*args, raise_on_non_zero_exit: true)
sudo_if_needed(*systemd_command(*args), raise_on_non_zero_exit: raise_on_non_zero_exit)
end
Expand Down
41 changes: 11 additions & 30 deletions lib/capistrano/tasks/solid_queue.rake
Original file line number Diff line number Diff line change
Expand Up @@ -5,41 +5,29 @@ plugin = self
namespace :solid_queue do # rubocop:disable Metrics
desc "Generate solid_queue systemd service"
task :generate do
on roles(fetch(:solid_queue_role)) do |role|
service_file = File.expand_path("../../templates/solid_queue.service.erb", __FILE__)
erb = File.read(service_file)
File.write "solid_queue.service", ERB.new(erb, trim_mode: "-").result(binding)
on roles(fetch(:solid_queue_role)) do
File.write "solid_queue.service", plugin.service_unit(binding)
end
end

desc "Install solid_queue systemd service"
task :install do
on roles(fetch(:solid_queue_role)) do |role|
execute :mkdir, "-p", fetch(:solid_queue_systemd_conf_dir)

service_file = File.expand_path("../../templates/solid_queue.service.erb", __FILE__)
erb = File.read(service_file)
file = StringIO.new(ERB.new(erb, trim_mode: "-").result(binding))

systemd_path = fetch(:solid_queue_systemd_conf_dir)
path = "#{systemd_path}/#{fetch(:solid_queue_service_unit_name)}.service"

execute :mkdir, "-p", systemd_path
upload! file, path
on roles(fetch(:solid_queue_role)) do
tmp_path = File.join(fetch(:tmp_dir), plugin.service_unit_file)
upload! StringIO.new(plugin.service_unit(binding)), tmp_path
plugin.sudo_if_needed("mkdir", "-p", fetch(:solid_queue_systemd_conf_dir))
plugin.sudo_if_needed("mv", tmp_path, File.join(fetch(:solid_queue_systemd_conf_dir), plugin.service_unit_file))

# Reload systemd
plugin.execute_systemd("daemon-reload")
invoke "solid_queue:enable"
plugin.execute_systemd("enable", fetch(:solid_queue_service_unit_name))
end
end

desc "Uninstall solid_queue systemd service"
task :uninstall do
invoke "solid_queue:disable"
on roles(fetch(:solid_queue_role)) do |role|
systemd_path = fetch(:solid_queue_systemd_conf_dir)
execute :rm, "-f", "#{systemd_path}/#{fetch(:solid_queue_service_unit_name)}*"

on roles(fetch(:solid_queue_role)) do
plugin.sudo_if_needed("rm", "-f", File.join(fetch(:solid_queue_systemd_conf_dir), plugin.service_unit_file))
plugin.execute_systemd("daemon-reload")
end
end
Expand Down Expand Up @@ -86,17 +74,10 @@ namespace :solid_queue do # rubocop:disable Metrics
end
end

desc "Reload solid_queue service via systemd"
task :reload do
on roles(fetch(:solid_queue_role)) do
plugin.execute_systemd("reload", fetch(:solid_queue_service_unit_name))
end
end

desc "Get solid_queue service status via systemd"
task :status do
on roles(fetch(:solid_queue_role)) do
plugin.execute_systemd("status", fetch(:solid_queue_service_unit_name))
plugin.execute_systemd("status", fetch(:solid_queue_service_unit_name), raise_on_non_zero_exit: false)
end
end
end
1 change: 0 additions & 1 deletion lib/capistrano/templates/solid_queue.service.erb
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,6 @@ Environment='<%= variable.to_s.upcase %>=<%= capture(:printf, "%s", %("#{value.t
<% end -%>
WorkingDirectory=<%= current_path %>
ExecStart=<%= capture(:echo, SSHKit.config.command_map[:bundle]).strip %> exec rake solid_queue:start
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| -%>
Expand Down
6 changes: 0 additions & 6 deletions sig/capistrano/solid_queue.rbs

This file was deleted.

4 changes: 4 additions & 0 deletions test/capistrano/test_service_unit.rb
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,10 @@ def test_user_service_has_no_user_line
refute_match(/^User=/, generate_unit)
end

def test_service_has_no_reload_command
refute_includes generate_unit, "ExecReload"
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"]
Expand Down
7 changes: 7 additions & 0 deletions test/capistrano/test_systemctl_failure.rb
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,13 @@ def test_quiet_goes_on_when_systemctl_fails_as_system_user
end
end

def test_status_goes_on_when_the_service_is_not_running
run_cap("solid_queue:status", stage_config: 'SSHKit.config.command_map[:"/bin/systemctl"] = "false"') do |output, status|
assert_includes output, "false --user status app_solid_queue_preprod"
assert status.success?, output
end
end

def test_stop_aborts_when_systemctl_fails
run_cap("solid_queue:stop", stage_config: 'SSHKit.config.command_map[:"/bin/systemctl"] = "false"') do |output, status|
assert_includes output, "false --user stop app_solid_queue_preprod"
Expand Down
82 changes: 82 additions & 0 deletions test/capistrano/test_tasks.rb
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# frozen_string_literal: true

require "test_helper"

class Capistrano::TestTasks < Minitest::Test
include CapistranoProject

USER_MODE = <<~RUBY
set :tmp_dir, "."
set :solid_queue_systemd_conf_dir, "units"
SSHKit.config.command_map[:"/bin/systemctl"] = "true"
RUBY

SYSTEM_MODE = <<~RUBY
set :solid_queue_systemctl_user, :system
set :tmp_dir, "."
set :solid_queue_systemd_conf_dir, "units"
SSHKit.config.command_map[:sudo] = "echo"
RUBY

def test_install_moves_the_unit_into_place_and_enables_it_on_the_same_host
stage_config = USER_MODE + <<~RUBY
task(:enable_task_invoked) { puts "enable task invoked" }
before "solid_queue:enable", :enable_task_invoked
RUBY

run_cap("solid_queue:install", stage_config: stage_config) do |output, status, dir|
assert status.success?, output
assert File.exist?(File.join(dir, "units", "app_solid_queue_preprod.service")), output
refute_includes output, "enable task invoked"
assert_includes output, "true --user enable app_solid_queue_preprod"
assert_operator output.index("true --user daemon-reload"), :<, output.index("true --user enable app_solid_queue_preprod")
end
end

def test_system_install_moves_the_unit_with_sudo
run_cap("solid_queue:install", stage_config: SYSTEM_MODE) do |output, status|
assert status.success?, output
assert_includes output, "echo mv ./app_solid_queue_preprod.service units/app_solid_queue_preprod.service"
end
end

def test_uninstall_removes_only_this_service
stage_config = USER_MODE + <<~RUBY
FileUtils.mkdir_p("units")
FileUtils.touch(["units/app_solid_queue_preprod.service", "units/app_solid_queue_preprod_eu.service"])
RUBY

run_cap("solid_queue:uninstall", stage_config: stage_config) do |output, status, dir|
assert status.success?, output
refute File.exist?(File.join(dir, "units", "app_solid_queue_preprod.service")), output
assert File.exist?(File.join(dir, "units", "app_solid_queue_preprod_eu.service")), output
end
end

def test_system_uninstall_removes_the_unit_with_sudo
run_cap("solid_queue:uninstall", stage_config: SYSTEM_MODE) do |output, status|
assert status.success?, output
assert_includes output, "echo rm -f units/app_solid_queue_preprod.service"
end
end

def test_deploy_stops_then_starts_the_service
stage_config = <<~RUBY
set :sshkit_backend, SSHKit::Backend::Printer
set :repo_url, "https://example.invalid/app.git"
RUBY

run_cap("deploy", stage_config: stage_config) do |output, status|
assert status.success?, output
assert_equal %w[solid_queue:stop solid_queue:start], output.scan(/^\d\d:\d\d (solid_queue:\w+)$/).flatten
end
end

def test_there_is_no_reload_task
run_cap("--tasks") do |output, status|
assert status.success?, output
assert_includes output, "solid_queue:restart"
refute_includes output, "solid_queue:reload"
end
end
end
4 changes: 2 additions & 2 deletions test/test_helper.rb
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@
require "tmpdir"

module CapistranoProject
def run_cap(task, stage_config: "")
def run_cap(*tasks, stage_config: "")
Dir.mktmpdir do |dir|
FileUtils.mkdir_p(File.join(dir, "config", "deploy"))
File.write(File.join(dir, "Capfile"), <<~RUBY)
Expand All @@ -30,7 +30,7 @@ def run_cap(task, stage_config: "")
#{stage_config}
RUBY

output, status = Open3.capture2e(RbConfig.ruby, Gem.bin_path("capistrano", "cap"), "preprod", task, chdir: dir)
output, status = Open3.capture2e(RbConfig.ruby, Gem.bin_path("capistrano", "cap"), "preprod", *tasks, chdir: dir)
yield output, status, dir
end
end
Expand Down
Loading