diff --git a/docs/systemd.md b/docs/systemd.md index ca4b99be90..6dd6401e37 100644 --- a/docs/systemd.md +++ b/docs/systemd.md @@ -1,19 +1,18 @@ # systemd -[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. +[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. ## 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. +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). +Note that this uses the systemd preferred "simple" type where the start command +remains running in the foreground (does not fork and exit). ~~~~ ini [Unit] @@ -37,8 +36,8 @@ WatchdogSec=10 # Preferably configure a non-privileged user # User= -# The path to the your application code root directory. -# Also replace the "" place holders below with this path. +# The path to your application code root directory. +# Also replace the "" placeholders below with this path. # Example /home/username/myapp WorkingDirectory= @@ -64,33 +63,31 @@ Restart=always WantedBy=multi-user.target ~~~~ -See [systemd.exec](https://www.freedesktop.org/software/systemd/man/systemd.exec.html) +See +[systemd.exec](https://www.freedesktop.org/software/systemd/man/systemd.exec.html) 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, including when upgraded puma, and is compatible with both -clustered mode and application preload. - -**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 -above.) Here is a sample puma.socket, matching the ports used in the -above puma.service: +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, including when upgraded Puma, and is +compatible with both clustered mode and application preload. + +**Note:** Any wrapper scripts which `exec`, or other indirections in `ExecStart` +may result in activated socket file descriptors being closed before reaching 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]. + +Configure one or more `ListenStream` sockets in a companion `*.socket` unit file +to use socket activation. 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] @@ -113,31 +110,32 @@ Backlog=1024 WantedBy=sockets.target ~~~~ -See [systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html) +See +[systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html) for additional configuration details. -Note that the above configurations will work with Puma in either -single process or cluster mode. +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`). +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:`. +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 +By default, you need to configure Puma to have binds matching with all ListenStream statements. Any mismatched systemd ListenStreams will be closed by -puma. +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 +`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. @@ -146,8 +144,8 @@ binds that's not socket activated. ## Usage -Without socket activation, use `systemctl` as root (e.g. via `sudo`) as -with other system services: +Without socket activation, use `systemctl` as root (i.e., via `sudo`) as with +other system services: ~~~~ sh # After installing or making changes to puma.service @@ -156,35 +154,35 @@ systemctl daemon-reload # Enable so it starts on boot systemctl enable puma.service -# Initial start up. +# Initial startup. systemctl start puma.service # Check status systemctl status puma.service -# A normal restart. Warning: listeners sockets will be closed +# A normal restart. Warning: listener's sockets will be closed # while a new puma process initializes. systemctl restart puma.service ~~~~ -With socket activation, several but not all of these commands should -be run for both socket and service: +With socket activation, several but not all of these commands should be run for +both socket and service: ~~~~ sh # After installing or making changes to either puma.socket or # puma.service. systemctl daemon-reload -# Enable both socket and service so they start on boot. Alternatively -# you could leave puma.service disabled and systemd will start it on -# first use (with startup lag on first request) +# Enable both socket and service, so they start on boot. Alternatively +# you could leave puma.service disabled, and systemd will start it on +# the first use (with startup lag on the first request) systemctl enable puma.socket puma.service -# Initial start up. The Requires directive (see above) ensures the +# Initial startup. The Requires directive (see above) ensures the # socket is started before the service. systemctl start puma.socket puma.service -# Check status of both socket and service. +# Check the status of both socket and service. systemctl status puma.socket puma.service # A "hot" restart, with systemd keeping puma.socket listening and @@ -197,8 +195,8 @@ systemctl restart puma.service systemctl restart puma.socket puma.service ~~~~ -Here is sample output from `systemctl status` with both service and -socket running: +Here is sample output from `systemctl status` with both service and socket +running: ~~~~ ● puma.socket - Puma HTTP Server Accept Sockets @@ -231,14 +229,12 @@ Apr 07 08:40:19 hx puma[28320]: Use Ctrl-C to stop ### 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. +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