capistrano-solid_queue 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2905775672a64a7e909bf749cf7fec4496cc5a26be4a22060b9a32520842af57
-  data.tar.gz: a2f839777ed810896d596d2365499535c98b62a33cb99484e1311bb285cb9bdf
+  metadata.gz: b7813736623d35e8c351f92ec7d0cf06cc5afcb022b1db19a498d21bf3de0186
+  data.tar.gz: e7972afc9f6ac146598eccb98f5dbe6c2a9bcfd9c048fa0e741722d0deef4fbd
 SHA512:
-  metadata.gz: ea28c7a078a31b4aaa77e98ba21fa4294dbe5fcd7381d6d87d4665ca4a72b684bc056ccb33640854eb5de98bea870d8320db3bd492d00633933e9e63076642e1
-  data.tar.gz: 4102571e45a97c1a2204a0960558239379bd0dd0b47c342d0208febd8d1d7a10d633c2122248bbc870f8bb6559bef3e05511cb847547d4449ffd51fd64a2bb6c
+  metadata.gz: 132a4b6047cdcebc00e0480839db4544805620b9666e881beac83aee567f3ab2798a86cf18c0bef568eb529accae52213e765789e0c7c23007d603c321617f2c
+  data.tar.gz: 209afad9b358b958a96fd5c48feffb10620a2ac0fa963d29d0f4ccc70e08568ea3b3368a80ae45f384ae7fe2dc01149de9ee5ba73b7f93d4992a29832a028923

data/CHANGELOG.md

@@ -6,6 +6,37 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-11-09
+
+### 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)).
+- 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)).
+- The service starts Solid Queue with `bin/jobs`, as Solid Queue documents, instead of `rake solid_queue:start`. The application needs `bin/jobs`: Rails 8 applications have it, and `bin/rails solid_queue:install` creates it. Run `cap <stage> solid_queue:install` again to update an installed service ([#16](https://github.com/codeur/capistrano-solid_queue/pull/16)).
+
+### 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)).
+- `solid_queue:quiet`: Solid Queue has no quiet mode, the `SIGTERM` it sent started a shutdown. `solid_queue:stop` stops Solid Queue gracefully ([#16](https://github.com/codeur/capistrano-solid_queue/pull/16)).
+
+### 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 README says when the gem isn't needed (Solid Queue running inside Puma) and how to pass `bin/jobs` options ([#16](https://github.com/codeur/capistrano-solid_queue/pull/16)).
+- 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
 
 ### Fixed
@@ -33,7 +64,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
 - Initial release.
 
-[unreleased]: https://github.com/codeur/capistrano-solid_queue/compare/v0.1.3...HEAD
+[unreleased]: https://github.com/codeur/capistrano-solid_queue/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/codeur/capistrano-solid_queue/compare/v0.1.3...v0.2.0
 [0.1.3]: https://github.com/codeur/capistrano-solid_queue/compare/v0.1.2...v0.1.3
 [0.1.2]: https://github.com/codeur/capistrano-solid_queue/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/codeur/capistrano-solid_queue/compare/v0.1.0...v0.1.1

data/README.md

@@ -1,19 +1,19 @@
 # Capistrano Systemd integration for SolidQueue
 
+Runs [Solid Queue](https://github.com/rails/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:
 
 ```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: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 +53,82 @@ 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 has registered a Capistrano `hook` to run `bundle exec cap solid_queue:restart` after deploy.
+The plugin registers these Capistrano hooks:
+
+- 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.
+
 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.
+
+Solid Queue reads the options of `bin/jobs` from environment variables too, for instance:
+
+```ruby
+set :solid_queue_service_unit_env_vars, ["SOLID_QUEUE_CONFIG=config/calendar.yml", "SOLID_QUEUE_SKIP_RECURRING=true"]
+```
+
 ## 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.
@@ -86,7 +145,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
 

data/lib/capistrano/solid_queue/version.rb

@@ -2,6 +2,6 @@
 
 module Capistrano
   module SolidQueue
-    VERSION = "0.1.3"
+    VERSION = "0.2.0"
   end
 end

data/lib/capistrano/solid_queue.rb

@@ -11,6 +11,8 @@ module Capistrano
         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
@@ -18,12 +20,19 @@ module Capistrano
       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

data/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
@@ -58,13 +46,6 @@ namespace :solid_queue do # rubocop:disable Metrics
     end
   end
 
-  desc "Quiet solid_queue (start graceful termination)"
-  task :quiet do
-    on roles(fetch(:solid_queue_role)) do
-      plugin.execute_systemd("kill", "-s", "SIGTERM", fetch(:solid_queue_service_unit_name), raise_on_non_zero_exit: false)
-    end
-  end
-
   desc "Start solid_queue service via systemd"
   task :start do
     on roles(fetch(:solid_queue_role)) do
@@ -86,17 +67,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

data/lib/capistrano/templates/solid_queue.service.erb

@@ -1,18 +1,26 @@
 [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('"', '\"')}")) %>'
 <% end -%>
 WorkingDirectory=<%= current_path %>
-ExecStart=<%= capture(:echo, SSHKit.config.command_map[:bundle]).strip %> exec rake solid_queue:start
-ExecReload=/bin/kill -TSTP $MAINPID
+ExecStart=<%= capture(:echo, SSHKit.config.command_map[:bundle]).strip %> exec bin/jobs
 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

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: capistrano-solid_queue
 version: !ruby/object:Gem::Version
-  version: 0.1.3
+  version: 0.2.0
 platform: ruby
 authors:
 - Brice TEXIER
-bindir: exe
+bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -15,32 +15,30 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
+        version: '3.5'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '3.0'
-description: Adds support for SolidQueue to Capistrano 3.x
+        version: '3.5'
+description: Capistrano tasks and deploy hooks that install, start, stop and restart
+  Solid Queue as a systemd service.
 email:
 - brice@codeur.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".standard.yml"
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - LICENSE.txt
 - README.md
-- Rakefile
 - lib/capistrano/solid_queue.rb
 - lib/capistrano/solid_queue/version.rb
 - lib/capistrano/tasks/solid_queue.rake
 - lib/capistrano/templates/solid_queue.service.erb
-- sig/capistrano/solid_queue.rbs
 homepage: https://github.com/codeur/capistrano-solid_queue
 licenses:
 - MIT
@@ -48,7 +46,7 @@ metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/codeur/capistrano-solid_queue
   source_code_uri: https://github.com/codeur/capistrano-solid_queue
-  changelog_uri: https://github.com/codeur/capistrano-solid_queue/releases
+  changelog_uri: https://github.com/codeur/capistrano-solid_queue/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -56,7 +54,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.6.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -65,5 +63,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.16
 specification_version: 4
-summary: Adds support for SolidQueue to Capistrano 3.x
+summary: Run Solid Queue as a systemd service with Capistrano
 test_files: []

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/standardrb/standard
-ruby_version: 2.6

data/Rakefile

@@ -1,14 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "minitest/test_task"
-
-Minitest::TestTask.create do |t|
-  # Capistrano 3.20 emits circular require warnings under Ruby 3.4 with -w.
-  # Keep test output clean until upstream fixes the warning path.
-  t.warning = false
-end
-
-require "standard/rake"
-
-task default: %i[test standard]

data/sig/capistrano/solid_queue.rbs

@@ -1,6 +0,0 @@
-module Capistrano
-  class SolidQueue
-    VERSION: String
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
-  end
-end