systemd

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.

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
below.

  1. [Unit]
  2. Description=Puma HTTP Server
  3. After=network.target
  5. # Uncomment for socket activation (see below)
  6. # Requires=puma.socket
  8. [Service]
  9. # Foreground process (do not use --daemon in ExecStart or config.rb)
  10. Type=simple
  12. # Preferably configure a non-privileged user
  13. # User=
  15. # The path to the puma application root
  16. # Also replace the "<WD>" place holders below with this path.
  17. WorkingDirectory=
  19. # Helpful for debugging socket activation, etc.
  20. # Environment=PUMA_DEBUG=1
  22. # The command to start Puma. This variant uses a binstub generated via
  23. # `bundle binstubs puma --path ./sbin` in the WorkingDirectory
  24. # (replace "<WD>" below)
  25. ExecStart=<WD>/sbin/puma -b tcp://0.0.0.0:9292 -b ssl://0.0.0.0:9293?key=key.pem&cert=cert.pem
  27. # Variant: Use config file with `bind` directives instead:
  28. # ExecStart=<WD>/sbin/puma -C config.rb
  29. # Variant: Use `bundle exec --keep-file-descriptors puma` instead of binstub
  31. Restart=always
  33. [Install]
  34. WantedBy=multi-user.target

See systemd.exec
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: 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:

  1. [Unit]
  2. Description=Puma HTTP Server Accept Sockets
  4. [Socket]
  5. ListenStream=0.0.0.0:9292
  6. ListenStream=0.0.0.0:9293
  8. # AF_UNIX domain socket
  9. # SocketUser, SocketGroup, etc. may be needed for Unix domain sockets
  10. # ListenStream=/run/puma.sock
  12. # Socket options matching Puma defaults
  13. NoDelay=true
  14. ReusePort=true
  15. Backlog=1024
  17. [Install]
  18. WantedBy=sockets.target

See systemd.socket
for additional configuration details.

Note that the above configurations will work with Puma in either
single process or cluster mode.

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
with other system services:

  1. # After installing or making changes to puma.service
  2. systemctl daemon-reload
  4. # Enable so it starts on boot
  5. systemctl enable puma.service
  7. # Initial start up.
  8. systemctl start puma.service
  10. # Check status
  11. systemctl status puma.service
  13. # A normal restart. Warning: listeners sockets will be closed
  14. # while a new puma process initializes.
  15. systemctl restart puma.service

With socket activation, several but not all of these commands should
be run for both socket and service:

  1. # After installing or making changes to either puma.socket or
  2. # puma.service.
  3. systemctl daemon-reload
  5. # Enable both socket and service so they start on boot.  Alternatively
  6. # you could leave puma.service disabled and systemd will start it on
  7. # first use (with startup lag on first request)
  8. systemctl enable puma.socket puma.service
  10. # Initial start up. The Requires directive (see above) ensures the
  11. # socket is started before the service.
  12. systemctl start puma.socket puma.service
  14. # Check status of both socket and service.
  15. systemctl status puma.socket puma.service
  17. # A "hot" restart, with systemd keeping puma.socket listening and
  18. # providing to the new puma (master) instance.
  19. systemctl restart puma.service
  21. # A normal restart, needed to handle changes to
  22. # puma.socket, such as changing the ListenStream ports. Note
  23. # daemon-reload (above) should be run first.
  24. systemctl restart puma.socket puma.service

Here is sample output from systemctl status with both service and
socket running:

  1. ● puma.socket - Puma HTTP Server Accept Sockets
  2.    Loaded: loaded (/etc/systemd/system/puma.socket; enabled; vendor preset: enabled)
  3.    Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
  4.    Listen: 0.0.0.0:9233 (Stream)
  5.            0.0.0.0:9234 (Stream)
  7. Apr 07 08:40:19 hx systemd[874]: Listening on Puma HTTP Server Accept Sockets.
  9. ● puma.service - Puma HTTP Server
  10.    Loaded: loaded (/etc/systemd/system/puma.service; enabled; vendor preset: enabled)
  11.    Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
  12.  Main PID: 28320 (ruby)
  13.    CGroup: /system.slice/puma.service
  14.            ├─28320 puma 3.3.0 (tcp://0.0.0.0:9233,ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem) [app]
  15.            ├─28323 puma: cluster worker 0: 28320 [app]
  16.            └─28327 puma: cluster worker 1: 28320 [app]
  18. Apr 07 08:40:19 hx puma[28320]: Puma starting in cluster mode...
  19. Apr 07 08:40:19 hx puma[28320]: * Version 3.3.0 (ruby 2.2.4-p230), codename: Jovial Platypus
  20. Apr 07 08:40:19 hx puma[28320]: * Min threads: 0, max threads: 16
  21. Apr 07 08:40:19 hx puma[28320]: * Environment: production
  22. Apr 07 08:40:19 hx puma[28320]: * Process workers: 2
  23. Apr 07 08:40:19 hx puma[28320]: * Phased restart available
  24. Apr 07 08:40:19 hx puma[28320]: * Activated tcp://0.0.0.0:9233
  25. Apr 07 08:40:19 hx puma[28320]: * Activated ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem
  26. 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.

  1. [Unit]
  2. Description=Puma HTTP Forking Server
  3. After=network.target
  5. [Service]
  6. # Background process configuration (use with --daemon in ExecStart)
  7. Type=forking
  9. # Preferably configure a non-privileged user
  10. # User=
  12. # The path to the puma application root
  13. # Also replace the "<WD>" place holders below with this path.
  14. WorkingDirectory=
  16. # The command to start Puma
  17. # (replace "<WD>" below)
  18. ExecStart=bundle exec puma -C <WD>/shared/puma.rb --daemon
  20. # The command to stop Puma
  21. # (replace "<WD>" below)
  22. ExecStop=bundle exec pumactl -S <WD>/shared/tmp/pids/puma.state stop
  24. # Path to PID file so that systemd knows which is the master process
  25. PIDFile=<WD>/shared/tmp/pids/puma.pid
  27. # Should systemd restart puma?
  28. # Use "no" (the default) to ensure no interference when using
  29. # stop/start/restart via `pumactl`.  The "on-failure" setting might
  30. # work better for this purpose, but you must test it.
  31. # Use "always" if only `systemctl` is used for start/stop/restart, and
  32. # reconsider if you actually need the forking config.
  33. Restart=no
  35. [Install]
  36. WantedBy=multi-user.target

capistrano3-puma

By default,
capistrano3-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.

  1. stage=production # or different stage, as needed
  2. cap $stage puma:start --dry-run
  3. cap $stage puma:stop  --dry-run