capistrano3-puma 6.0.0 → 6.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d265909a3107947404ed854ac684f27f5bbd65cc9aea7fd9efb39c1aa3b42f
-  data.tar.gz: f4c31b71706468b2c090a8ef00a21e4df9766bf99e6dedc70f1d78f47dc49f06
+  metadata.gz: a0e3b56cceac3a829240f070437a0e232c5c79f38370989572024ab08af9038a
+  data.tar.gz: 67e21b9c665facae205f009b694d6a2652c0a9546c95a3db3739fac5c5a0159f
 SHA512:
-  metadata.gz: 43cc928a86e88f01c25739b9f94716b00cbbe3233618a4f05a8c4079bc8a77529ec8de2631b3ceb561a246e807dec15ca4448f0b1e76f4fd497d78b172e3e6d5
-  data.tar.gz: ef9e24fd09b905f096a8452ac9f84c78d385e4c1d75e20ec99c209cbcc9587dfffdb8942c9c17358f47ce7613f770d47bef81c8dd549d7abc46134d634c63590
+  metadata.gz: 3c216aed4f83378c3ecf0a2bb0cab5c7046eb1a2ad9bf280691ea4325e6d583dbf98640c14e7c8e793eb8ee9c3645d2c0da17b9205e20db3c48b330fa4ed80ed
+  data.tar.gz: 4b19a5a3c2513402c5987ec0e501e5dcb19d7fb47e80b3ad4eec037d1a4171c1ba9645c0bad51f8cc28f5c8f16f215084015f1e32861784fd13ccbe364a995a1

data/CHANGELOG.md

@@ -1,7 +1,24 @@
 # Changelog
 
-[Unreleased](https://github.com/seuros/capistrano-puma/compare/v5.2.0...master)
-- Removed support for support for monit and upstart. (will add them back if someone is willing to maintain them)
+## [6.2.0](https://github.com/seuros/capistrano-puma/tree/6.2.0) (2025-06-22)
+
+[Full Changelog](https://github.com/seuros/capistrano-puma/compare/v6.1.0...6.2.0)
+- Harmonized interface with capistrano-sidekiq for better ecosystem consistency
+- Aligned configuration variable naming patterns
+- Unified systemd command execution methods
+- Standardized template search order across both gems
+- Added documentation reference to example application
+
+## [6.1.0](https://github.com/seuros/capistrano-puma/tree/6.1.0) (2025-01-21)
+
+[Full Changelog](https://github.com/seuros/capistrano-puma/compare/v6.0.0...6.1.0)
+- Restored default value for `puma_bind` to fix socket activation (Issue #387)
+- Added documentation for puma.rb symlink requirement in v6.0.0 (Issue #384)
+- Made WatchdogSec configurable via `puma_systemd_watchdog_sec` (Issue #373)
+- Improved documentation for first-time setup and troubleshooting (Issues #377, #376, #372)
+- Added migration guide for upgrading from v5 to v6
+- Added troubleshooting section for common issues
+- Removed support for monit and upstart (will add them back if someone is willing to maintain them)
 - Sync configuration with capistrano-sidekiq
 - Support for notify systemd service. Add sd_notify gem to your Gemfile.
 - Add example application for easier testing.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2013-2022 Abdelkader Boudih
+Copyright (c) 2013-2025 Abdelkader Boudih
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/README.md

@@ -1,6 +1,17 @@
 [![Gem Version](https://badge.fury.io/rb/capistrano3-puma.svg)](http://badge.fury.io/rb/capistrano3-puma)
 # Capistrano::Puma
 
+Puma integration for Capistrano - providing systemd service management and zero-downtime deployments for Puma 5.1+.
+
+## Example Application
+
+For a complete working example of this gem in action, see the [capistrano-example-app](https://github.com/seuros/capistrano-example-app) which demonstrates:
+- Rails 8.0 deployment with Capistrano
+- Puma 6.0 with systemd socket activation
+- Zero-downtime deployments
+- rbenv integration
+- Nginx configuration examples
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -15,6 +26,34 @@ And then execute:
 
     $ bundle
 
+## Upgrading from Version 5.x to 6.x
+
+Version 6.0 includes several breaking changes:
+
+### Breaking Changes:
+1. **Manual Puma Configuration**: The gem no longer generates `puma.rb` automatically
+   - You must create your own `config/puma.rb` in your repository
+   - Add it to `linked_files` in your `deploy.rb`
+
+2. **Default puma_bind Removed**: You must explicitly set the bind address
+   ```ruby
+   set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"
+   ```
+
+3. **Systemd Service Changes**: Services are now user-specific by default
+   - Services are created in `~/.config/systemd/user/`
+   - Run `cap production puma:install` again after upgrading
+
+### Migration Steps:
+1. Create your `config/puma.rb` if you don't have one
+2. Add to your `deploy.rb`:
+   ```ruby
+   append :linked_files, 'config/puma.rb'
+   set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"
+   ```
+3. Run `cap production puma:install` to update the systemd service
+4. Deploy as normal
+
 ## Usage
 ```ruby
     # Capfile
@@ -43,17 +82,53 @@ To make it work with rvm, rbenv and chruby, install the plugin after correspondi
 ### Config
 
 Puma configuration is expected to be in `config/puma.rb` or `config/puma/#{fetch(:puma_env)}.rb` and checked in your repository.
-Uploading the configuration via capistrano was removed as it was causing problems with custom configurations.
 
-### Deployment
+Starting with version 6.0.0, you need to manage the puma configuration file yourself. Here are the steps:
 
-Before running `$ bundle exec cap {stage} deploy` for the first time, install Puma on the deployment server. For example, if stage=production:
-```
+1. Create your puma configuration in `shared/config/puma.rb` on the server
+2. Add it to linked_files in your `deploy.rb`:
+   ```ruby
+   append :linked_files, 'config/puma.rb'
+   ```
+
+This ensures the puma configuration persists across deployments. The systemd service will start puma with `puma -e <environment>` from your app's current directory.
+
+### First-Time Setup (IMPORTANT! 🎉)
+
+**🙋 Hey there, human! Read this magical section and save yourself from confusion! 😊**
+
+Before your first deployment, you MUST install the Puma systemd service on your server:
+
+```bash
+# ✨ This only needs to be done once per server/stage - it's like a first date! 💝
 $ bundle exec cap production puma:install
 ```
 
-To uninstall,
+This command will:
+- 🏗️ Create the systemd service files for Puma
+- 🚀 Enable the service to start on boot
+- 🔐 Set up the proper user permissions
+
+**🎭 Plot twist:** Without running this command first, your deployment will succeed but Puma won't start! (We know, it's sneaky like that 😅)
+
+### Deployment
+
+After the initial setup, normal deployments will work as expected:
+```bash
+$ bundle exec cap production deploy
+```
+
+The deployment process will automatically restart Puma using the installed systemd service.
+
+To manually control the Puma service:
+```bash
+$ bundle exec cap production puma:start
+$ bundle exec cap production puma:stop
+$ bundle exec cap production puma:restart
 ```
+
+To uninstall the systemd service:
+```bash
 $ bundle exec cap production puma:uninstall
 ```
 
@@ -100,6 +175,8 @@ Configurable options, shown here with defaults: Please note the configuration op
 ```ruby
     set :puma_user, fetch(:user)
     set :puma_role, :web
+    set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"
+    set :puma_systemd_watchdog_sec, 10  # Set to 0 or false to disable watchdog
     set :puma_service_unit_env_files, []
     set :puma_service_unit_env_vars, []
 ```
@@ -109,6 +186,35 @@ __Notes:__ If you are setting values for variables that might be used by other p
 append :rbenv_map_bins, 'puma', 'pumactl'
 ```
 
+## Troubleshooting
+
+### Puma is not starting after deployment
+- Ensure you ran `cap production puma:install` before your first deployment
+- Check the service status: `cap production puma:status`
+- Check logs: `sudo journalctl -u your_app_puma_production -n 100`
+
+### Nginx 502 Bad Gateway errors
+This usually means nginx and puma have mismatched configurations:
+- If nginx expects a unix socket but puma binds to a port (or vice versa)
+- Ensure your `puma_bind` in deploy.rb matches your nginx upstream configuration
+- Common configurations:
+  ```ruby
+  # Unix socket (default)
+  set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"
+  
+  # TCP port
+  set :puma_bind, "tcp://0.0.0.0:3000"
+  ```
+
+### Puma keeps restarting (systemd watchdog kills it)
+- Your app may take longer than 10 seconds to boot
+- Disable or increase WatchdogSec (requires version 6.0.0+):
+  ```ruby
+  set :puma_systemd_watchdog_sec, 30  # 30 seconds
+  # or
+  set :puma_systemd_watchdog_sec, 0   # Disable watchdog
+  ```
+
 # Nginx documentation
 Nginx documentation was moved to [nginx.md](docs/nginx.md)
 

data/lib/capistrano/puma/systemd.rb

@@ -14,6 +14,7 @@ module Capistrano
       set_if_empty :puma_systemctl_bin, -> { fetch(:systemctl_bin, '/bin/systemctl') }
       set_if_empty :puma_service_unit_name, -> { "#{fetch(:application)}_puma_#{fetch(:stage)}" }
       set_if_empty :puma_enable_socket_service, false
+      set_if_empty :puma_systemd_watchdog_sec, 10
 
       set_if_empty :puma_service_unit_env_files, -> { fetch(:service_unit_env_files, []) }
       set_if_empty :puma_service_unit_env_vars, -> { fetch(:service_unit_env_vars, []) }
@@ -25,10 +26,6 @@ module Capistrano
       set_if_empty :puma_service_templates_path, fetch(:service_templates_path, 'config/deploy/templates')
     end
 
-    def expanded_bundle_command
-      backend.capture(:echo, SSHKit.config.command_map[:bundle]).strip
-    end
-
     def fetch_systemd_unit_path
       if fetch(:puma_systemctl_user) == :system
         "/etc/systemd/system/"

data/lib/capistrano/puma.rb

@@ -6,18 +6,18 @@ module Capistrano
     def puma_switch_user(role, &block)
       user = puma_user(role)
       if user == role.user
-        block.call
+        yield
       else
-        backend.as user do
-          block.call
-        end
+        backend.as(user, &block)
       end
     end
 
     def puma_user(role)
       properties = role.properties
+      return role.user unless properties
+      
       properties.fetch(:puma_user) || # local property for puma only
-          fetch(:puma_user) ||
+          fetch(:puma_user, nil) ||
           properties.fetch(:run_as) || # global property across multiple capistrano gems
           role.user
     end
@@ -53,11 +53,7 @@ module Capistrano
           File.expand_path("../templates/#{from}.rb.erb", __FILE__)
       ].detect { |path| File.file?(path) }
       erb = File.read(file)
-      if Gem::Version.new(RUBY_VERSION) < Gem::Version.new('2.6')
-        StringIO.new(ERB.new(erb, nil, '-').result(binding))
-      else
-        StringIO.new(ERB.new(erb, trim_mode: '-').result(binding))
-      end
+      StringIO.new(ERB.new(erb, trim_mode: '-').result(binding))
     end
 
     def template_puma(from, to, role)
@@ -102,6 +98,10 @@ module Capistrano
         PumaBind.new(m, etype.to_sym, address)
       end
     end
+
+    def expanded_bundle_command
+      backend.capture(:echo, SSHKit.config.command_map[:bundle]).strip
+    end
   end
 
   class Puma < Capistrano::Plugin
@@ -109,9 +109,10 @@ module Capistrano
 
     def set_defaults
       set_if_empty :puma_role, :web
-      set_if_empty :puma_env, -> { fetch(:rack_env, fetch(:rails_env, fetch(:stage))) }
+      set_if_empty :puma_env, -> { fetch(:rack_env, fetch(:rails_env, fetch(:rake_env, fetch(:stage)))) }
+      set_if_empty :puma_bind, -> { "unix://#{File.join(shared_path, 'tmp', 'sockets', 'puma.sock')}" }
       set_if_empty :puma_access_log, -> { File.join(shared_path, 'log', "puma.log") }
-      set_if_empty :puma_error_log, -> { File.join(shared_path, 'log', "puma.log") }
+      set_if_empty :puma_error_log, -> { File.join(shared_path, 'log', "puma_error.log") }
 
       # Chruby, Rbenv and RVM integration
       append :chruby_map_bins, 'puma', 'pumactl' if fetch(:chruby_map_bins)

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

@@ -16,10 +16,16 @@ After=syslog.target network.target
 
 [Service]
 Type=<%= service_unit_type %>
-WatchdogSec=10
+<% if fetch(:puma_systemd_watchdog_sec) && fetch(:puma_systemd_watchdog_sec) > 0 %>
+WatchdogSec=<%= fetch(:puma_systemd_watchdog_sec) %>
+<% end %>
 <%="User=#{puma_user(@role)}" if fetch(:puma_systemctl_user) == :system %>
 WorkingDirectory=<%= current_path %>
+<% if fetch(:puma_use_login_shell) %>
+ExecStart=/bin/bash -lc '<%= expanded_bundle_command %> exec puma -e <%= fetch(:puma_env) %>'
+<% else %>
 ExecStart=<%= expanded_bundle_command %> exec puma -e <%= fetch(:puma_env) %>
+<% end %>
 ExecReload=/bin/kill -USR1 $MAINPID
 <%- Array(fetch(:puma_service_unit_env_files)).each do |file| %>
 <%="EnvironmentFile=#{file}" -%>

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capistrano3-puma
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.2.0
 platform: ruby
 authors:
 - Abdelkader Boudih
 bindir: bin
 cert_chain: []
-date: 2025-01-01 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano
@@ -98,7 +98,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Puma integration for Capistrano
 test_files: []