Project

puma-plugin-systemd

0.04
No commit activity in last 3 years
No release in over 3 years
puma-plugin-systemdsj26/puma-plugin-systemdHomepageDocumentationSource CodeBug TrackerWiki
Puma integration with systemd: notify, status, watchdog
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Popularity
Downloads
31,950
Stars
38
Forks
20
Watchers
4
 Releases
Current version
0.1.5
Total releases
5
First release
2018-05-04
Latest release
2020-08-29
 Issues
Open Issues
0
Closed Issues
5
Total Issues
5
Issue Closure Rate
100%
 Pull Requests
Open Pull Requests
0
Closed Pull Requests
5
Merged Pull Requests
7
Pull Request Acceptance Rate
58%
 Development
Primary Language
Ruby
Licenses
MIT
Average date of last 50 commits
2020-01-17
Reverse Dependencies
0

 Dependencies

Development

bundler
~> 1.13
minitest
~> 5.0
rake
>= 12.3.3

Runtime

json
>= 0
puma
>= 3.6, < 5
 Project Readme

⚠️ Systemd support is now built-in to Puma. This plugin is deprecated in favor of the native support.

Puma Systemd Plugin

Build results Gem version

Puma integration with systemd for better daemonising under modern Linux systemds: notify, status, watchdog.

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

Installation

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

Usage

Notify

Make sure puma is being started using a systemd service unit with 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

Status

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[30762]: puma.service: Executing: /app/bin/puma -C config/puma.rb -e production
Oct 24 00:54:58 web puma[32234]: [32234] Puma starting in cluster mode...
Oct 24 00:54:58 web puma[32234]: [32234] * Version 3.6.0 (ruby 2.3.1-p112), codename: Sleepy Sunday Serenity
Oct 24 00:54:58 web puma[32234]: [32234] * Min threads: 8, max threads: 64
Oct 24 00:26:55 web puma[32234]: [32234] * Environment: production
Oct 24 00:26:55 web puma[32234]: [32234] * Process workers: 2
Oct 24 00:26:55 web puma[32234]: [32234] * Phased restart available
Oct 24 00:26:55 web puma[32234]: [32234] * Listening on unix:///app/tmp/sockets/puma.sock?backlog=1024
Oct 24 00:26:55 web puma[32234]: [32234] Use Ctrl-C to stop
Oct 24 00:26:55 web puma[32234]: [32234] * systemd: notify ready
Oct 24 00:26:55 web puma[32234]: [32251] + Gemfile in context: /app/Gemfile
Oct 24 00:26:55 web systemd[1]: Started puma.
Oct 24 00:26:55 web puma[32234]: [32234] * systemd: watchdog detected (30000000usec)
Oct 24 00:26:55 web puma[32234]: [32253] + Gemfile in context: /app/Gemfile

Watchdog

Adding a 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.

Development

After checking out the repo, run script/setup to install dependencies. Then, run 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.

Example

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

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/sj26/puma-plugin-systemd.

License

The gem is available as open source under the terms of the MIT License.