kotovalexarian-likes-github/puma--puma
1
0
Fork 0
mirror of https://github.com/puma/puma.git synced 2022-11-09 13:48:40 -05:00
Code Releases Activity

Additional docs/systemd refinements (#1329)

Browse source 
* More docs/systemd refinements

 * Section renamed Alternative Forking Configuration with explanation
   given for when to use this.
 * capistrano3-puma in sub-section with consolidated dry-run shell
   commands
 * Section Service Configuration contrasts and references Forking
   section
 * Streamline config samples and highlight using ini format

* More intro to docs/systemd, alt forking section

* Add docs/systemd link to tools/jungle/README, for parity

* Add systemd, alt-forking Always and WantedBy

* Add another link to systemd from README, capistrano section

* minor typo
This commit is contained in:
David Kellum 2017-06-26 14:27:31 -07:00 • committed by Nate Berkopec
parent c264e6aba8
commit 5814e39b0e
3 changed files with 97 additions and 34 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

5
README.md
View file

@ -339,6 +339,11 @@ $ bundle exec cap puma:stop
$ bundle exec cap puma:phased-restart
```
See
[docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md),
including the last section, if using this in conjunction with systemd
(all recent, major distributions of Linux).
## Contributing
To run the test suite:

122
docs/systemd.md
View file

@ -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
# 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
# Alternatively with a config file (in WorkingDirectory) and
# comparable `bind` directives
# 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,16 @@ 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. 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:
~~~~
~~~~ ini
[Unit]
Description=Puma HTTP Server Accept Sockets
@ -169,29 +181,71 @@ 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
## Alternative Forking 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:
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 command to start Puma
# Replace "<WD>" below, with the application root or working directory
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=

4
tools/jungle/README.md
View file

@ -7,3 +7,7 @@ See `/tools/jungle/init.d` for tools to use with init.d and start-stop-daemon.
## Upstart
See `/tools/jungle/upstart` for Ubuntu's upstart scripts.
## Systemd
See [/docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md).