diff --git a/docs/systemd.md b/docs/systemd.md new file mode 100644 index 00000000..2d6d449e --- /dev/null +++ b/docs/systemd.md @@ -0,0 +1,78 @@ +# 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. Below is a sample +puma.service configuration file for systemd: + +~~~~ +[Unit] +Description=Puma HTTP Server +After=network.target + +[Service] +# Foreground process (do not use --daemon in ExecStart or config.rb) +Type=simple + +# Preferably configure a non-privileged user +# User= + +# Specify the path to your puma application root +# 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 below) +# You can alternatively use `bundle exec --keep-file-descriptors puma` +# ExecStart=/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 +# ExecStart=/sbin/puma -C config.rb + +Restart=always + +[Install] +WantedBy=multi-user.target +~~~~ + +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. 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: + +~~~~ +[Unit] +Description=Puma HTTP Server Accept Sockets + +[Socket] +ListenStream=0.0.0.0:9292 +ListenStream=0.0.0.0:9293 + +# AF_UNIX domain socket +# SocketUser, SocketGroup, etc. may be needed for Unix domain sockets +# ListenStream=/run/puma.sock + +# Socket options matching what Puma wants +NoDelay=true +ReusePort=true + +[Install] +WantedBy=sockets.target +~~~~ + +See [systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html) +for additional details.