systemd docs refined

README.md

@@ -238,7 +238,7 @@ To perform a restart, there are 2 builtin mechanisms:
 
 No code is shared between the current and restarted process, so it should be safe to issue a restart any place where you would manually stop Puma and start it again.
 
-If the new process is unable to load, it will simply exit. You should therefore run Puma under a supervisor when using it in production.
+If the new process is unable to load, it will simply exit. You should therefore run Puma under a process monitor (see below) when using it in production.
 
 ### Normal vs Hot vs Phased Restart
 
@@ -295,9 +295,15 @@ Because of various platforms not being able to implement certain things, the fol
 
 `pumactl` is a simple CLI frontend to the control/status app described above.  Please refer to `pumactl --help` for available commands.
 
-## Managing multiple Pumas / init.d / upstart scripts
+## Process Monitors
 
-If you want an easy way to manage multiple scripts at once, check [tools/jungle](https://github.com/puma/puma/tree/master/tools/jungle) for init.d and upstart scripts.
+Process monitors or supervisors will at minimum provide start of Puma
+on system boot. Modern process monitors like systemd or upstart
+further provide continous monitoring and restarts for increased
+reliability in production environments:
+
+* [tools/jungle](https://github.com/puma/puma/tree/master/tools/jungle) for sysvinit (init.d) and upstart
+* [docs/systemd](https://github.com/puma/puma/blob/master/docs/systemd.md)
 
 ## Capistrano deployment
 

docs/systemd.md

@@ -11,6 +11,9 @@ puma.service configuration file for systemd:
 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
@@ -33,7 +36,7 @@ Type=simple
 
 # Alternatively with a config file (in WorkingDirectory) and
 # comparable `bind` directives
-# ExecStart=<WorkingDirectory>/sbin/puma -C config.rb
+# ExecStart=<WD>/sbin/puma -C config.rb
 
 Restart=always
 
@@ -66,13 +69,102 @@ ListenStream=0.0.0.0:9293
 # SocketUser, SocketGroup, etc. may be needed for Unix domain sockets
 # ListenStream=/run/puma.sock
 
-# Socket options matching what Puma wants
+# Socket options matching Puma defaults
 NoDelay=true
 ReusePort=true
+Backlog=1024
 
 [Install]
 WantedBy=sockets.target
 ~~~~
 
 See [systemd.socket](https://www.freedesktop.org/software/systemd/man/systemd.socket.html)
-for additional details.
+for additional configuration details.
+
+Note that the above configurations will work with Puma in either
+single process or cluster mode.
+
+## Usage
+
+Without socket activation, use `systemctl` as root (e.g. via `sudo`) as
+with other system services:
+
+~~~~ sh
+# After installing or making changes to puma.service
+systemctl daemon-reload
+
+# Enable so it starts on boot
+systemctl enable puma.service
+
+# Initial start up.
+systemctl start puma.service
+
+# Check status
+systemctl status puma.service
+
+# A normal restart. Warning: listeners 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:
+
+~~~~ 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)
+systemctl enable puma.socket puma.service
+
+# Initial start up. 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.
+systemctl status puma.socket puma.service
+
+# A "hot" restart, with systemd keeping puma.socket listening and
+# providing to the new puma (master) instance.
+systemctl restart puma.service
+
+# A normal restart, needed to handle changes to
+# puma.socket, such as changing the ListenStream ports. Note
+# daemon-reload (above) should be run first.
+systemctl restart puma.socket puma.service
+~~~~
+
+Here is sample output from `systemctl status` with both service and
+socket running:
+
+~~~~
+● puma.socket - Puma HTTP Server Accept Sockets
+   Loaded: loaded (/etc/systemd/system/puma.socket; enabled; vendor preset: enabled)
+   Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
+   Listen: 0.0.0.0:9233 (Stream)
+           0.0.0.0:9234 (Stream)
+
+Apr 07 08:40:19 hx systemd[874]: Listening on Puma HTTP Server Accept Sockets.
+
+● puma.service - Puma HTTP Server
+   Loaded: loaded (/etc/systemd/system/puma.service; enabled; vendor preset: enabled)
+   Active: active (running) since Thu 2016-04-07 08:40:19 PDT; 1h 2min ago
+ Main PID: 28320 (ruby)
+   CGroup: /system.slice/puma.service
+           ├─28320 puma 3.3.0 (tcp://0.0.0.0:9233,ssl://0.0.0.0:9234?key=key.pem&cert=cert.pem) [app]
+           ├─28323 puma: cluster worker 0: 28320 [app]
+           └─28327 puma: cluster worker 1: 28320 [app]
+
+Apr 07 08:40:19 hx puma[28320]: Puma starting in cluster mode...
+Apr 07 08:40:19 hx puma[28320]: * Version 3.3.0 (ruby 2.2.4-p230), codename: Jovial Platypus
+Apr 07 08:40:19 hx puma[28320]: * Min threads: 0, max threads: 16
+Apr 07 08:40:19 hx puma[28320]: * Environment: production
+Apr 07 08:40:19 hx puma[28320]: * Process workers: 2
+Apr 07 08:40:19 hx puma[28320]: * Phased restart available
+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
+~~~~