capistrano3-puma 6.0.0 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0d265909a3107947404ed854ac684f27f5bbd65cc9aea7fd9efb39c1aa3b42f
-  data.tar.gz: f4c31b71706468b2c090a8ef00a21e4df9766bf99e6dedc70f1d78f47dc49f06
+  metadata.gz: 9d2f07d6e635bd2c3dd87706742d9f417140165102818a2f05f7be0b9d4e031d
+  data.tar.gz: ce613f7509c20d4520a599a0f93a9a6d5a0d485037c11aa94914fdca4c0fffcd
 SHA512:
-  metadata.gz: 43cc928a86e88f01c25739b9f94716b00cbbe3233618a4f05a8c4079bc8a77529ec8de2631b3ceb561a246e807dec15ca4448f0b1e76f4fd497d78b172e3e6d5
-  data.tar.gz: ef9e24fd09b905f096a8452ac9f84c78d385e4c1d75e20ec99c209cbcc9587dfffdb8942c9c17358f47ce7613f770d47bef81c8dd549d7abc46134d634c63590
+  metadata.gz: c303ca5c2c0d1f28e288bffcb84ffe5ee69a708ad2c08bf000cc3f0004cdef369da1822b00b564d8c6c9e2ded34e54de7aa43a256e95384d6d7c29195a9538a1
+  data.tar.gz: 6750f2ae9a2c356cf1e099b5ea2e1144a6fc843bd5b9828e2843a50b15977df4e5cdc43b98216dff0bc02e40661d6934bb5a519e85734edb3a334e0a7e76a437

data/CHANGELOG.md

@@ -1,7 +1,15 @@
 # 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.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

@@ -15,6 +15,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 +71,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 +164,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 +175,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, []) }

data/lib/capistrano/puma.rb

@@ -110,6 +110,7 @@ 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_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") }
 

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

@@ -16,7 +16,9 @@ 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 %>
 ExecStart=<%= expanded_bundle_command %> exec puma -e <%= fetch(:puma_env) %>

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capistrano3-puma
 version: !ruby/object:Gem::Version
-  version: 6.0.0
+  version: 6.1.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: []