puma 3.8.2 → 3.12.6

data/docs/signals.md

@@ -36,8 +36,61 @@ Puma cluster responds to these signals:
 - `TTIN` increment the worker count by 1
 - `TTOU` decrement the worker count by 1
 - `TERM` send `TERM` to worker. Worker will attempt to finish then exit.
-- `USR2` restart workers
-- `USR1` restart workers in phases, a rolling restart.
-- `HUP`  reopen log files defined in stdout_redirect configuration parameter
+- `USR2` restart workers. This also reloads puma configuration file, if there is one.
+- `USR1` restart workers in phases, a rolling restart. This will not reload configuration file.
+- `HUP`  reopen log files defined in stdout_redirect configuration parameter. If there is no stdout_redirect option provided it will behave like `INT`
 - `INT` equivalent of sending Ctrl-C to cluster. Will attempt to finish then exit.
 - `CHLD`
+
+## Callbacks order in case of different signals
+
+### Start application
+
+```
+puma configuration file reloaded, if there is one
+* Pruning Bundler environment
+puma configuration file reloaded, if there is one
+
+before_fork
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```
+
+### Send USR2
+
+```
+on_worker_shutdown
+on_restart
+
+puma configuration file reloaded, if there is one
+
+before_fork
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```
+
+### Send USR1
+
+```
+on_worker_shutdown
+on_worker_fork
+after_worker_fork
+
+Gemfile in context
+
+on_worker_boot
+
+Code of the app is loaded and running
+```

data/docs/systemd.md

@@ -3,10 +3,21 @@
 [systemd](https://www.freedesktop.org/wiki/Software/systemd/) is a
 commonly available init system (PID 1) on many Linux distributions. It
 offers process monitoring (including automatic restarts) and other
-useful features for running Puma in production. Below is a sample
-puma.service configuration file for systemd:
+useful features for running Puma in production.
 
-~~~~
+## Service Configuration
+
+Below is a sample puma.service configuration file for systemd, which
+can be copied or symlinked to /etc/systemd/system/puma.service, or if
+desired, using an application or instance specific name.
+
+Note that this uses the systemd preferred "simple" type where the
+start command remains running in the foreground (does not fork and
+exit). See also, the
+[Alternative Forking Configuration](#alternative-forking-configuration)
+below.
+
+~~~~ ini
 [Unit]
 Description=Puma HTTP Server
 After=network.target
@@ -21,22 +32,21 @@ Type=simple
 # Preferably configure a non-privileged user
 # User=
 
-# Specify the path to your puma application root
-# WorkingDirectory=
+# The path to the puma application root
+# Also replace the "<WD>" place holders below with this path.
+WorkingDirectory=
 
 # Helpful for debugging socket activation, etc.
 # Environment=PUMA_DEBUG=1
 
-# The command to start Puma
-# Here we are using a binstub generated via:
-# `bundle binstubs puma --path ./sbin`
-# in the WorkingDirectory (replace <WD> below)
-# You can alternatively use `bundle exec --keep-file-descriptors puma`
-# ExecStart=<WD>/sbin/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
-
-# Alternatively with a config file (in WorkingDirectory) and
-# comparable `bind` directives
+# The command to start Puma. This variant uses a binstub generated via
+# `bundle binstubs puma --path ./sbin` in the WorkingDirectory
+# (replace "<WD>" below)
+ExecStart=<WD>/sbin/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
+
+# Variant: Use config file with `bind` directives instead:
 # ExecStart=<WD>/sbin/puma -C config.rb
+# Variant: Use `bundle exec --keep-file-descriptors puma` instead of binstub
 
 Restart=always
 
@@ -50,14 +60,22 @@ for additional details.
 ## Socket Activation
 
 systemd and puma also support socket activation, where systemd opens
-the listening socket(s) in advance and provides them to the puma master
-process on startup. Among other advantages, this keeps listening
-sockets open across puma restarts and achieves graceful restarts. To
-use socket activation, configure one or more `ListenStream`
-sockets in a companion `*.socket` systemd config file. Here is a sample
-puma.socket, matching the ports used in the above puma.service:
-
-~~~~
+the listening socket(s) in advance and provides them to the puma
+master process on startup. Among other advantages, this keeps
+listening sockets open across puma restarts and achieves graceful
+restarts, including when upgraded puma, and is compatible with both
+clustered mode and application preload.
+
+**Note:** Socket activation doesn't currently work on jruby. This is
+tracked in [#1367].
+
+To use socket activation, configure one or more `ListenStream` sockets
+in a companion `*.socket` unit file. Also uncomment the associated
+`Requires` directive for the socket unit in the service file (see
+above.) Here is a sample puma.socket, matching the ports used in the
+above puma.service:
+
+~~~~ ini
 [Unit]
 Description=Puma HTTP Server Accept Sockets
 
@@ -84,6 +102,16 @@ for additional configuration details.
 Note that the above configurations will work with Puma in either
 single process or cluster mode.
 
+### Sockets and symlinks
+
+When using releases folders, you should set the socket path using the
+shared folder path (ex. `/srv/projet/shared/tmp/puma.sock`), not the
+release folder path (`/srv/projet/releases/1234/tmp/puma.sock`).
+
+Puma will detect the release path socket as different than the one provided by
+systemd and attempt to bind it again, resulting in the exception
+ `There is already a server bound to:`.
+
 ## Usage
 
 Without socket activation, use `systemctl` as root (e.g. via `sudo`) as
@@ -169,29 +197,76 @@ Apr 07 08:40:19 hx puma[28320]: * Activated ssl://0.0.0.0:9234?key=key.pem&cert=
 Apr 07 08:40:19 hx puma[28320]: Use Ctrl-C to stop
 ~~~~
 
-## Alternative background process configuration
-
-If Capistrano and [capistrano3-puma](https://github.com/seuros/capistrano-puma) tasks are used you can use the following configuration. In this case, you would skip systemd Socket Activation, since Puma handles the socket by itself:
+## Alternative Forking Configuration
+
+Other systems/tools might expect or need puma to be run as a
+"traditional" forking server, for example so that the `pumactl`
+command can be used directly and outside of systemd for
+stop/start/restart. This use case is incompatible with systemd socket
+activation, so it should not be configured. Below is an alternative
+puma.service config sample, using `Type=forking` and the `--daemon`
+flag in `ExecStart`. Here systemd is playing a role more equivalent to
+SysV init.d, where it is responsible for starting Puma on boot
+(multi-user.target) and stopping it on shutdown, but is not performing
+continuous restarts. Therefore running Puma in cluster mode, where the
+master can restart workers, is highly recommended. See the systemd
+[Restart] directive for details.
+
+~~~~ ini
+[Unit]
+Description=Puma HTTP Forking Server
+After=network.target
 
-~~~~
 [Service]
 # Background process configuration (use with --daemon in ExecStart)
 Type=forking
 
-# To learn which exact command is to be used to execute at "ExecStart" of this
-# Service, ask Capistrano: `cap <stage> puma:start --dry-run`. Your result
-# may differ from this example, for example if you use a Ruby version
-# manager. `<WD>` is short for "your working directory". Replace it with your
-# path.
+# Preferably configure a non-privileged user
+# User=
+
+# The path to the puma application root
+# Also replace the "<WD>" place holders below with this path.
+WorkingDirectory=
+
+# The command to start Puma
+# (replace "<WD>" below)
 ExecStart=bundle exec puma -C <WD>/shared/puma.rb --daemon
 
-# To learn which exact command is to be used to execute at "ExecStop" of this
-# Service, ask Capistrano: `cap <stage> puma:stop --dry-run`. Your result
-# may differ from this example, for example if you use a Ruby version
-# manager. `<WD>` is short for "your working directory". Replace it with your
-# path.
+# The command to stop Puma
+# (replace "<WD>" below)
 ExecStop=bundle exec pumactl -S <WD>/shared/tmp/pids/puma.state stop
 
-# PIDFile setting is required in order to work properly
+# Path to PID file so that systemd knows which is the master process
 PIDFile=<WD>/shared/tmp/pids/puma.pid
+
+# Should systemd restart puma?
+# Use "no" (the default) to ensure no interference when using
+# stop/start/restart via `pumactl`.  The "on-failure" setting might
+# work better for this purpose, but you must test it.
+# Use "always" if only `systemctl` is used for start/stop/restart, and
+# reconsider if you actually need the forking config.
+Restart=no
+
+[Install]
+WantedBy=multi-user.target
 ~~~~
+
+### capistrano3-puma
+
+By default,
+[capistrano3-puma](https://github.com/seuros/capistrano-puma) uses
+`pumactl` for deployment restarts, outside of systemd.  To learn the
+exact commands that this tool would use for `ExecStart` and
+`ExecStop`, use the following `cap` commands in dry-run mode, and
+update from the above forking service configuration accordingly. Note
+also that the configured `User` should likely be the same as the
+capistrano3-puma `:puma_user` option.
+
+~~~~ sh
+stage=production # or different stage, as needed
+cap $stage puma:start --dry-run
+cap $stage puma:stop  --dry-run
+~~~~
+
+[Restart]: https://www.freedesktop.org/software/systemd/man/systemd.service.html#Restart=
+[#1367]: https://github.com/puma/puma/issues/1367