Puma Systemd Plugin
- Notify systemd when puma has booted and is ready to handle requests
- Publish puma stats as systemd service status for a quick overview
- Use the watchdog to make sure your puma processes are healthy and haven't locked up or run out of memory
Puma already natively supports socket activation.
Add this gem to your Gemfile with puma and then bundle:
gem "puma" gem "puma-plugin-systemd"
Add it to your puma config:
# config/puma.rb bind "tcp://127.0.0.1:9292" workers 2 threads 8, 16 plugin :systemd
Make sure puma is being started using a systemd service unit
Type=notify, something like:
# puma.service [Service] Type=notify User=puma WorkingDirectory=/app ExecStart=/app/bin/puma -C config/puma.rb -e production ExecReload=/bin/kill -USR1 $MAINPID Restart=always KillMode=mixed
Running in notify mode as above should just start publishing puma stats as
systemd status. Running
systemctl status puma.service or similar should
result in a Status line in your status output:
app@web:~$ sudo systemctl status puma.service ● puma.service - puma Loaded: loaded (/etc/systemd/system/puma.service; enabled; vendor preset: enabled) Active: active (running) since Mon 2016-10-24 00:26:55 UTC; 5s ago Main PID: 32234 (ruby2.7) Status: "puma 3.6.0 cluster: 2/2 workers: 8/16 threads, 8 available, 0 backlog" Tasks: 10 Memory: 167.9M CPU: 7.150s CGroup: /system.slice/puma.service ├─32234 puma 3.6.0 (unix:///app/tmp/sockets/puma.sock?backlog=1024) [app] ├─32251 puma: cluster worker 0: 32234 [app] └─32253 puma: cluster worker 1: 32234 [app] Oct 24 00:26:10 web systemd: puma.service: Executing: /app/bin/puma -C config/puma.rb -e production Oct 24 00:54:58 web puma:  Puma starting in cluster mode... Oct 24 00:54:58 web puma:  * Version 3.6.0 (ruby 2.3.1-p112), codename: Sleepy Sunday Serenity Oct 24 00:54:58 web puma:  * Min threads: 8, max threads: 64 Oct 24 00:26:55 web puma:  * Environment: production Oct 24 00:26:55 web puma:  * Process workers: 2 Oct 24 00:26:55 web puma:  * Phased restart available Oct 24 00:26:55 web puma:  * Listening on unix:///app/tmp/sockets/puma.sock?backlog=1024 Oct 24 00:26:55 web puma:  Use Ctrl-C to stop Oct 24 00:26:55 web puma:  * systemd: notify ready Oct 24 00:26:55 web puma:  + Gemfile in context: /app/Gemfile Oct 24 00:26:55 web systemd: Started puma. Oct 24 00:26:55 web puma:  * systemd: watchdog detected (30000000usec) Oct 24 00:26:55 web puma:  + Gemfile in context: /app/Gemfile
WatchdogSec=30 or similar to your systemd service file will tell
puma systemd to ping systemd at half the specified interval to ensure the
service is running and healthy.
After checking out the repo, run
script/setup to install dependencies. Then,
rake test to run the tests. You can also run
script/console for an
interactive prompt that will allow you to experiment.
To install this gem onto your local machine, run
bundle exec rake install. To
release a new version, update the version number in
version.rb, and then run
bundle exec rake release, which will create a git tag for the version, push
git commits and tags, and push the
.gem file to rubygems.org.
There is an
example directory which contains a Dockerfile and basic
configuration for testing. To use it:
cd example # Build an image with systemd, puma and the plugin configured docker build --tag example . # Start a new container from the image in the background docker run --name example --privileged --detach --rm example # Show puma systemd integration docker exec example systemctl status puma # Stop the container docker exec example halt
Bug reports and pull requests are welcome on GitHub at https://github.com/sj26/puma-plugin-systemd.
The gem is available as open source under the terms of the MIT License.