capistrano3-puma 3.1.1 → 8.0.0

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,92 +26,147 @@ 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
 
     require 'capistrano/puma'
     install_plugin Capistrano::Puma  # Default puma tasks
-    install_plugin Capistrano::Puma::Workers  # if you want to control the workers (in cluster mode)
-    install_plugin Capistrano::Puma::Jungle # if you need the jungle tasks
-    install_plugin Capistrano::Puma::Monit  # if you need the monit tasks
-    install_plugin Capistrano::Puma::Nginx  # if you want to upload a nginx site template
+    install_plugin Capistrano::Puma::Systemd
 ```
 
 To prevent loading the hooks of the plugin, add false to the load_hooks param.
 ```ruby
     # Capfile
 
-    require 'capistrano/puma'
     install_plugin Capistrano::Puma, load_hooks: false  # Default puma tasks without hooks
-    install_plugin Capistrano::Puma::Monit, load_hooks: false  # Monit tasks without hooks
+```
+
+To make it work with rvm, rbenv and chruby, install the plugin after corresponding library inclusion.
+```ruby
+    # Capfile
+
+    require 'capistrano/rbenv'
+    require 'capistrano/puma'
+    install_plugin Capistrano::Puma
 ```
 
 ### Config
 
-To list available tasks use `cap -T`
+Puma configuration is expected to be in `config/puma.rb` or `config/puma/#{fetch(:puma_env)}.rb` and checked in your repository.
 
-To upload puma config use:
-```ruby
-cap production puma:config
-```
-By default the file located in  `shared/puma.config`
+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'
+   ```
 
-Ensure that `tmp/pids` and ` tmp/sockets log` are shared (via `linked_dirs`):
+This ensures the puma configuration persists across deployments. The systemd service will start puma with `puma -e <environment>` from your app's current directory.
 
-`This step is mandatory before deploying, otherwise puma server won't start`
+### First-Time Setup (IMPORTANT! 🎉)
 
-### Nginx
+**🙋 Hey there, human! Read this magical section and save yourself from confusion! 😊**
 
-To upload a nginx site config (eg. /etc/nginx/sites-enabled/) use:
-```ruby
-cap production puma:nginx_config
+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 customize these two templates locally before uploading use:
+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
 ```
-rails g capistrano:nginx_puma:config
+
+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
 ```
 
-if your nginx server configuration is not located in `/etc/nginx`, you may need to customize:
-```ruby
-set :nginx_sites_available_path, "/etc/nginx/sites-available"
-set :nginx_sites_enabled_path, "/etc/nginx/sites-enabled"
+To uninstall the systemd service:
+```bash
+$ bundle exec cap production puma:uninstall
 ```
 
-By default, `nginx_config` will be executed with `:web` role. But you can assign it to a different role:
-```ruby
-set :puma_nginx, :foo
+### Full Task List
 ```
-or define a standalone one:
-```ruby
-role :puma_nginx, %w{root@example.com}
+$ 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
 
-### Jungle
+A sample application is provided to show how to use this gem at https://github.com/seuros/capistrano-example-app
 
-For Jungle tasks (beta), these options exist:
-```ruby
-    set :puma_jungle_conf, '/etc/puma.conf'
-    set :puma_run_path, '/usr/local/bin/run-puma'
-```
+### Systemd Socket Activation
 
-### Multi bind
+Systemd socket activation starts your app upon first request if it is not already running
 
-Multi-bind can be set with an array in the puma_bind variable
 ```ruby
-  set :puma_bind, %w(tcp://0.0.0.0:9292 unix:///tmp/puma.sock)
+    set :puma_enable_socket_service, true
 ```
-    * Listening on tcp://0.0.0.0:9220
-    * Listening on unix:///tmp/puma.sock
 
-### Active Record
+For more information on socket activation have a look at the `systemd.socket` [man page](https://man7.org/linux/man-pages/man5/systemd.socket.5.html).
 
-For ActiveRecord the following line to your deploy.rb
-```ruby
-    set :puma_init_active_record, true
+To restart the listening socket using Systemd run
 ```
+cap puma:systemd:restart_socket
+```
+This would also restart the puma instance as the puma service depends on the socket service being active
 
 ### Other configs
 
@@ -108,36 +174,12 @@ Configurable options, shown here with defaults: Please note the configuration op
 
 ```ruby
     set :puma_user, fetch(:user)
-    set :puma_rackup, -> { File.join(current_path, 'config.ru') }
-    set :puma_state, "#{shared_path}/tmp/pids/puma.state"
-    set :puma_pid, "#{shared_path}/tmp/pids/puma.pid"
-    set :puma_bind, "unix://#{shared_path}/tmp/sockets/puma.sock"    #accept array for multi-bind
-    set :puma_control_app, false
-    set :puma_default_control_app, "unix://#{shared_path}/tmp/sockets/pumactl.sock"
-    set :puma_conf, "#{shared_path}/puma.rb"
-    set :puma_access_log, "#{shared_path}/log/puma_access.log"
-    set :puma_error_log, "#{shared_path}/log/puma_error.log"
-    set :puma_role, :app
-    set :puma_env, fetch(:rack_env, fetch(:rails_env, 'production'))
-    set :puma_threads, [0, 16]
-    set :puma_workers, 0
-    set :puma_worker_timeout, nil
-    set :puma_init_active_record, false
-    set :puma_preload_app, false
-    set :puma_daemonize, false
-    set :puma_plugins, []  #accept array of plugins
-    set :puma_tag, fetch(:application)
-
-    set :nginx_config_name, "#{fetch(:application)}_#{fetch(:stage)}"
-    set :nginx_flags, 'fail_timeout=0'
-    set :nginx_http_flags, fetch(:nginx_flags)
-    set :nginx_server_name, "localhost #{fetch(:application)}.local"
-    set :nginx_sites_available_path, '/etc/nginx/sites-available'
-    set :nginx_sites_enabled_path, '/etc/nginx/sites-enabled'
-    set :nginx_socket_flags, fetch(:nginx_flags)
-    set :nginx_ssl_certificate, "/etc/ssl/certs/{fetch(:nginx_config_name)}.crt"
-    set :nginx_ssl_certificate_key, "/etc/ssl/private/{fetch(:nginx_config_name)}.key"
-    set :nginx_use_ssl, false
+    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, []
+    set :puma_service_unit_props, [] # Set extral puma service properties, such as ["MemoryMax=2G","TimeoutAbortSec=30"]
 ```
 
 __Notes:__ If you are setting values for variables that might be used by other plugins, use `append` instead of `set`. For example:
@@ -145,6 +187,38 @@ __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)
+
 ## Contributing
 
 1. Fork it

data/lib/capistrano/puma/nginx.rb

@@ -11,6 +11,8 @@ module Capistrano
       set_if_empty :nginx_http_flags, fetch(:nginx_flags)
       set_if_empty :nginx_socket_flags, fetch(:nginx_flags)
       set_if_empty :nginx_use_ssl, false
+      set_if_empty :nginx_use_http2, true
+      set_if_empty :nginx_downstream_uses_ssl, false
     end
 
     def define_tasks

data/lib/capistrano/puma/systemd.rb

@@ -0,0 +1,61 @@
+module Capistrano
+  class Puma::Systemd < Capistrano::Plugin
+    include PumaCommon
+
+    def register_hooks
+      after 'deploy:published', 'puma:smart_restart'
+    end
+
+    def define_tasks
+      eval_rakefile File.expand_path('../../tasks/systemd.rake', __FILE__)
+    end
+
+    def set_defaults
+      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, []) }
+      set_if_empty :puma_service_unit_props, -> { fetch(:service_unit_props, []) }
+
+      set_if_empty :puma_systemctl_user, -> { fetch(:systemctl_user, :user) }
+      set_if_empty :puma_enable_lingering, -> { fetch(:puma_systemctl_user) != :system }
+      set_if_empty :puma_lingering_user, -> { fetch(:lingering_user, fetch(:user)) }
+
+      set_if_empty :puma_service_templates_path, fetch(:service_templates_path, 'config/deploy/templates')
+    end
+
+    def fetch_systemd_unit_path
+      if fetch(:puma_systemctl_user) == :system
+        "/etc/systemd/system/"
+      else
+        home_dir = backend.capture :pwd
+        File.join(home_dir, ".config", "systemd", "user")
+      end
+    end
+
+    def systemd_command(*args)
+      command = [fetch(:puma_systemctl_bin)]
+
+      unless fetch(:puma_systemctl_user) == :system
+        command << "--user"
+      end
+
+      command + args
+    end
+
+    def sudo_if_needed(*command)
+      if fetch(:puma_systemctl_user) == :system
+        backend.sudo command.map(&:to_s).join(" ")
+      else
+        backend.execute(*command)
+      end
+    end
+
+    def execute_systemd(*args)
+      sudo_if_needed(*systemd_command(*args))
+    end
+  end
+end

data/lib/capistrano/puma.rb

@@ -1,23 +1,23 @@
 require 'capistrano/bundler'
-require "capistrano/plugin"
+require 'capistrano/plugin'
 
 module Capistrano
   module PumaCommon
     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
@@ -28,8 +28,14 @@ module Capistrano
       end.join("\n")
     end
 
+    def service_unit_type
+      ## Jruby don't support notify
+      return "simple" if RUBY_ENGINE == "jruby"
+      ## Puma 6.1+ has built-in sd_notify support
+      fetch(:puma_service_unit_type, "notify")
+    end
 
-    def template_puma(from, to, role)
+    def compiled_template_puma(from, role)
       @role = role
       file = [
           "lib/capistrano/templates/#{from}-#{role.hostname}-#{fetch(:stage)}.rb",
@@ -45,77 +51,76 @@ module Capistrano
           File.expand_path("../templates/#{from}.rb.erb", __FILE__)
       ].detect { |path| File.file?(path) }
       erb = File.read(file)
-      backend.upload! StringIO.new(ERB.new(erb, nil, '-').result(binding)), to
+      StringIO.new(ERB.new(erb, trim_mode: '-').result(binding))
     end
-  end
 
-  class Puma < Capistrano::Plugin
-    include PumaCommon
-
-    def define_tasks
-      eval_rakefile File.expand_path('../tasks/puma.rake', __FILE__)
+    def template_puma(from, to, role)
+      backend.upload! compiled_template_puma(from, role), to
     end
 
-    def set_defaults
-      set_if_empty :puma_role, :app
-      set_if_empty :puma_env, -> { fetch(:rack_env, fetch(:rails_env, fetch(:stage))) }
-      # Configure "min" to be the minimum number of threads to use to answer
-      # requests and "max" the maximum.
-      set_if_empty :puma_threads, [0, 16]
-      set_if_empty :puma_workers, 0
-      set_if_empty :puma_rackup, -> { File.join(current_path, 'config.ru') }
-      set_if_empty :puma_state, -> { File.join(shared_path, 'tmp', 'pids', 'puma.state') }
-      set_if_empty :puma_pid, -> { File.join(shared_path, 'tmp', 'pids', 'puma.pid') }
-      set_if_empty :puma_bind, -> { File.join("unix://#{shared_path}", 'tmp', 'sockets', 'puma.sock') }
-      set_if_empty :puma_control_app, false
-      set_if_empty :puma_default_control_app, -> { File.join("unix://#{shared_path}", 'tmp', 'sockets', 'pumactl.sock') }
-      set_if_empty :puma_conf, -> { File.join(shared_path, 'puma.rb') }
-      set_if_empty :puma_access_log, -> { File.join(shared_path, 'log', 'puma_access.log') }
-      set_if_empty :puma_error_log, -> { File.join(shared_path, 'log', 'puma_error.log') }
-      set_if_empty :puma_init_active_record, false
-      set_if_empty :puma_preload_app, false
-      set_if_empty :puma_daemonize, false
-      set_if_empty :puma_tag, ''
+    PumaBind = Struct.new(:full_address, :kind, :address) do
+      def unix?
+        kind == :unix
+      end
 
-      # Chruby, Rbenv and RVM integration
-      append :chruby_map_bins, 'puma', 'pumactl'
-      append :rbenv_map_bins, 'puma', 'pumactl'
-      append :rvm_map_bins, 'puma', 'pumactl'
+      def ssl?
+        kind == :ssl
+      end
 
-      # Bundler integration
-      append :bundle_bins, 'puma', 'pumactl'
-    end
+      def tcp
+        kind == :tcp || ssl?
+      end
 
-    def register_hooks
-      after 'deploy:check', 'puma:check'
-      after 'deploy:finished', 'puma:smart_restart'
-    end
+      def local
+        if unix?
+          self
+        else
+          PumaBind.new(
+            localize_address(full_address),
+            kind,
+            localize_address(address)
+          )
+        end
+      end
 
-    def puma_workers
-      fetch(:puma_workers, 0)
-    end
+      private
 
-    def puma_preload_app?
-      fetch(:puma_preload_app)
+      def localize_address(address)
+        address.gsub(/0\.0\.0\.0(.+)/, "127.0.0.1\\1")
+      end
     end
 
-    def puma_daemonize?
-      fetch(:puma_daemonize)
+    def puma_binds
+      Array(fetch(:puma_bind)).map do |m|
+        etype, address  = /(tcp|unix|ssl):\/{1,2}(.+)/.match(m).captures
+        PumaBind.new(m, etype.to_sym, address)
+      end
     end
 
-    def puma_plugins
-      Array(fetch(:puma_plugins)).collect do |bind|
-        "plugin '#{bind}'"
-      end.join("\n")
+    def expanded_bundle_command
+      backend.capture(:echo, SSHKit.config.command_map[:bundle]).strip
     end
+  end
 
-    def upload_puma_rb(role)
-      template_puma 'puma', fetch(:puma_conf), role
+  class Puma < Capistrano::Plugin
+    include PumaCommon
+
+    def set_defaults
+      set_if_empty :puma_role, :web
+      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_error.log") }
+
+      # Chruby, Rbenv and RVM integration
+      append :chruby_map_bins, 'puma', 'pumactl' if fetch(:chruby_map_bins)
+      append :rbenv_map_bins, 'puma', 'pumactl' if fetch(:rbenv_map_bins)
+      append :rvm_map_bins, 'puma', 'pumactl' if fetch(:rvm_map_bins)
+
+      # Bundler integration
+      append :bundle_bins, 'puma', 'pumactl'
     end
   end
 end
 
-require 'capistrano/puma/workers'
-require 'capistrano/puma/monit'
-require 'capistrano/puma/jungle'
-require 'capistrano/puma/nginx'
+require 'capistrano/puma/systemd'

data/lib/capistrano/tasks/nginx.rake

@@ -11,4 +11,12 @@ namespace :puma do
       end
     end
   end
+
+  desc 'Generate nginx configuration locally'
+  task :generate_nginx_config_locally do
+    fake_role = Struct.new(:hostname)
+    run_locally do
+      File.write('nginx.conf', git_plugin.compiled_template_puma("nginx_conf", fake_role.new("example.com")).string)
+    end
+  end
 end