systemd.md in piesync-puma-5.4.0.1

- old
+ new

@@ -6,50 +6,60 @@
 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
+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.
+exit).
 
 ~~~~ ini
 [Unit]
 Description=Puma HTTP Server
 After=network.target
 
 # Uncomment for socket activation (see below)
 # Requires=puma.socket
 
 [Service]
-# Foreground process (do not use --daemon in ExecStart or config.rb)
-Type=simple
+# Puma supports systemd's `Type=notify` and watchdog service
+# monitoring, if the [sd_notify](https://github.com/agis/ruby-sdnotify) gem is installed,
+# as of Puma 5.1 or later.
+# On earlier versions of Puma or JRuby, change this to `Type=simple` and remove
+# the `WatchdogSec` line.
+Type=notify
 
+# If your Puma process locks up, systemd's watchdog will restart it within seconds.
+WatchdogSec=10
+
 # 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 path to the your application code root directory.
+# Also replace the "<YOUR_APP_PATH>" place holders below with this path.
+# Example /home/username/myapp
+WorkingDirectory=<YOUR_APP_PATH>
 
 # Helpful for debugging socket activation, etc.
 # Environment=PUMA_DEBUG=1
 
-# 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
+# SystemD will not run puma even if it is in your path. You must specify
+# an absolute URL to puma. For example /usr/local/bin/puma
+# Alternatively, create a binstub with `bundle binstubs puma --path ./sbin` in the WorkingDirectory
+ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/puma.rb
 
-# Variant: Use config file with `bind` directives instead:
-# ExecStart=<WD>/sbin/puma -C config.rb
+# Variant: Rails start.
+# ExecStart=/<FULLPATH>/bin/puma -C <YOUR_APP_PATH>/config/puma.rb ../config.ru
+
 # Variant: Use `bundle exec --keep-file-descriptors puma` instead of binstub
+# Variant: Specify directives inline.
+# ExecStart=/<FULLPATH>/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
 
+
 Restart=always
 
 [Install]
 WantedBy=multi-user.target
 ~~~~
@@ -64,11 +74,18 @@
 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
+**Note:** Any wrapper scripts which `exec`, or other indirections in
+`ExecStart`, may result in activated socket file descriptors being closed
+before they reach the puma master process. For example, if using `bundle exec`,
+pass the `--keep-file-descriptors` flag. `bundle exec` can be avoided by using a
+`puma` executable generated by `bundle binstubs puma`. This is tracked in
+[#1499].
+
+**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
@@ -110,10 +127,25 @@
 
 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:`.
 
+### Binding
+
+By default you need to configure puma to have binds matching with all
+ListenStream statements. Any mismatched systemd ListenStreams will be closed by
+puma.
+
+To automatically bind to all activated sockets, the option
+`--bind-to-activated-sockets` can be used. This matches the config DSL
+`bind_to_activated_sockets` statement. This will cause puma to create a bind
+automatically for any activated socket. When systemd socket activation is not
+enabled, this option does nothing.
+
+This also accepts an optional argument `only` (DSL: `'only'`) to discard any
+binds that's not socket activated.
+
 ## Usage
 
 Without socket activation, use `systemctl` as root (e.g. via `sudo`) as
 with other system services:
 
@@ -195,64 +227,10 @@
 Apr 07 08:40:19 hx puma[28320]: * Activated tcp://0.0.0.0:9233
 Apr 07 08:40:19 hx puma[28320]: * Activated ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem
 Apr 07 08:40:19 hx puma[28320]: Use Ctrl-C to stop
 ~~~~
 
-## 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
-
-# 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
-
-# The command to stop Puma
-# (replace "<WD>" below)
-ExecStop=bundle exec pumactl -S <WD>/shared/tmp/pids/puma.state stop
-
-# 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
@@ -268,5 +246,6 @@
 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
+[#1499]: https://github.com/puma/puma/issues/1499