capistrano3-puma 6.0.0.beta.1 → 6.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d2f6376b7e7c2838e8d06d7acb249e7b4cca75982bd440e2ad8952f80941132
-  data.tar.gz: 24ca957bc88c4f06d7a11dea7c70b72f77ca275bc46a77b6eb44f98bc51b5a3e
+  metadata.gz: 9d2f07d6e635bd2c3dd87706742d9f417140165102818a2f05f7be0b9d4e031d
+  data.tar.gz: ce613f7509c20d4520a599a0f93a9a6d5a0d485037c11aa94914fdca4c0fffcd
 SHA512:
-  metadata.gz: e0d445a032ad196fd65b8aa863c1fb049aec6f9e8f47f22cd2d05993555c354e110bfb397d1a001b6ee0b3cb9b19e38c3d6fe76bba47d5682b17992910a5717c
-  data.tar.gz: 9bba6960b9246b4877b02baa6339baf7a940caf16bcf54be2c0148850f96b7af1e68a07a97d03ac07bbc978275e1ea6ca44812587da942e176b674d230d2a88c
+  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,8 +71,72 @@ 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.
 
+Starting with version 6.0.0, you need to manage the puma configuration file yourself. Here are the steps:
+
+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
+```
+
+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
+```
+
+### Full Task List
+```
+$ cap -T puma
+cap puma:disable         # Disable Puma systemd service
+cap puma:enable          # Enable Puma systemd service
+cap puma:install         # Install Puma systemd service
+cap puma:reload          # Reload Puma service via systemd
+cap puma:restart         # Restart Puma service via systemd
+cap puma:restart_socket  # Restart Puma socket via systemd
+cap puma:smart_restart   # Restarts or reloads Puma service via systemd
+cap puma:start           # Start Puma service via systemd
+cap puma:status          # Get Puma service status via systemd
+cap puma:stop            # Stop Puma service via systemd
+cap puma:stop_socket     # Stop Puma socket via systemd
+cap puma:uninstall       # Uninstall Puma systemd service
+```
 ## Example
 
 A sample application is provided to show how to use this gem at https://github.com/seuros/capistrano-example-app
@@ -72,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, []
 ```
@@ -81,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

@@ -53,7 +53,11 @@ module Capistrano
           File.expand_path("../templates/#{from}.rb.erb", __FILE__)
       ].detect { |path| File.file?(path) }
       erb = File.read(file)
-      StringIO.new(ERB.new(erb, trim_mode: '-').result(binding))
+      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
     end
 
     def template_puma(from, to, role)
@@ -106,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/tasks/systemd.rake

@@ -52,7 +52,7 @@ namespace :puma do
       git_plugin.execute_systemd("enable", fetch(:puma_service_unit_name) + ".socket") if fetch(:puma_enable_socket_service)
 
       if fetch(:puma_systemctl_user) != :system && fetch(:puma_enable_lingering)
-        execute :loginctl, "enable-linger", fetch(:puma_lingering_user)
+        sudo "loginctl enable-linger #{fetch(:puma_lingering_user)}"
       end
     end
   end

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,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: capistrano3-puma
 version: !ruby/object:Gem::Version
-  version: 6.0.0.beta.1
+  version: 6.1.0
 platform: ruby
 authors:
 - Abdelkader Boudih
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2022-10-21 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: capistrano
@@ -95,12 +94,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '2.5'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: 1.3.1
+      version: '0'
 requirements: []
-rubygems_version: 3.2.33
-signing_key:
+rubygems_version: 3.6.7
 specification_version: 4
 summary: Puma integration for Capistrano
 test_files: []