diff --git a/.standard.yml b/.standard.yml index 8825305..0ed8183 100644 --- a/.standard.yml +++ b/.standard.yml @@ -1,3 +1,3 @@ # For available configuration options, see: # https://github.com/standardrb/standard -ruby_version: 2.6 +ruby_version: 3.1 diff --git a/CHANGELOG.md b/CHANGELOG.md index 724a3d8..2195d26 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 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 diff --git a/README.md b/README.md index a55d384..96596ff 100644 --- a/README.md +++ b/README.md @@ -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 ``` @@ -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/_solid_queue_.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. @@ -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 diff --git a/capistrano-solid_queue.gemspec b/capistrano-solid_queue.gemspec index 502da6d..7b99c4f 100644 --- a/capistrano-solid_queue.gemspec +++ b/capistrano-solid_queue.gemspec @@ -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 diff --git a/lib/capistrano/solid_queue.rb b/lib/capistrano/solid_queue.rb index 9301427..443154b 100644 --- a/lib/capistrano/solid_queue.rb +++ b/lib/capistrano/solid_queue.rb @@ -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 diff --git a/lib/capistrano/tasks/solid_queue.rake b/lib/capistrano/tasks/solid_queue.rake index fecec24..9a7d656 100644 --- a/lib/capistrano/tasks/solid_queue.rake +++ b/lib/capistrano/tasks/solid_queue.rake @@ -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 @@ -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 diff --git a/lib/capistrano/templates/solid_queue.service.erb b/lib/capistrano/templates/solid_queue.service.erb index a002793..a9353c8 100644 --- a/lib/capistrano/templates/solid_queue.service.erb +++ b/lib/capistrano/templates/solid_queue.service.erb @@ -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| -%> diff --git a/sig/capistrano/solid_queue.rbs b/sig/capistrano/solid_queue.rbs deleted file mode 100644 index 50a79b5..0000000 --- a/sig/capistrano/solid_queue.rbs +++ /dev/null @@ -1,6 +0,0 @@ -module Capistrano - class SolidQueue - VERSION: String - # See the writing guide of rbs: https://github.com/ruby/rbs#guides - end -end diff --git a/test/capistrano/test_service_unit.rb b/test/capistrano/test_service_unit.rb index f79994c..432e187 100644 --- a/test/capistrano/test_service_unit.rb +++ b/test/capistrano/test_service_unit.rb @@ -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"] diff --git a/test/capistrano/test_systemctl_failure.rb b/test/capistrano/test_systemctl_failure.rb index 07d2c0b..d4b2c99 100644 --- a/test/capistrano/test_systemctl_failure.rb +++ b/test/capistrano/test_systemctl_failure.rb @@ -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" diff --git a/test/capistrano/test_tasks.rb b/test/capistrano/test_tasks.rb new file mode 100644 index 0000000..15fcdf2 --- /dev/null +++ b/test/capistrano/test_tasks.rb @@ -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 diff --git a/test/test_helper.rb b/test/test_helper.rb index cc73451..4eb8203 100644 --- a/test/test_helper.rb +++ b/test/test_helper.rb @@ -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) @@ -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