Puma::Daemon

Unix processes have the ability to daemonize and go into the background.

This is not a trivial task: to properly daemonize a process must detach the from controlling terminal and run in the background as a system daemon.

In Ruby this is accomplished with the Process.daemon method, which receives two boolean arguments:

• Unless the first argument nochdir is true, it will change the current working directory to the root (“/”).

• Unless the second argument noclose is true, daemon() will also redirect standard input, standard output and standard error to /dev/null.

• Finally, it will return zero on success, or raise one of ` Errno::*` and pass the control to the subsequent Ruby code, which will now continue executing within a daemon.

For production deployments, tools like systemd offer much better alternative, including ability to cap overall memory and CPU consumed by the Puma and all of its workers using Linux cgroups.

The proliferation of Docker deployments meant that Puma is run on the foreground within a Docker container.

Finally, the code which previously daemonized Puma in version 4 was not really maintained, and for this reason was removed from Puma version 5.

We thought that while the core Puma removing daemonization was the right move, it felt useful in some occastions and so we created this gem to restore the daemonization functionality to Puma v5+.

We did not restore the daemon functionality for JRuby; so at the moment this will work with the MRI distribution, and possibly others that support Process.daemon(true, true).

For supported MRI Ruby Versions see the Github Workflow file.

Currently Puma versions 5 and 6 are supported.

Please see the list of open issues on the Issues Page. Any help is always welcomed.

This gem’s goal was to surgically augment Puma’s source code to restore daemonization by merely requiring puma/daemon.

We accomplished this goal by adding the daemonization call to the routine output_header() which is invoked by both Puma::Single runner and the Puma::Cluster runner at the very beginning of the launch process. While relatively brittle, particularly if the future versions of Puma change this, this approach seems to work with the currently released version of Puma (5 and 6).

If you run into problems, please submit an issue.

If you want to specify daemonize in your config file, simply include require 'puma/daemon' at the top of your config file:

With this method you can continue using the standard puma executable to get it started, but (and this is important) — you must remove any -d or --daemonize from the command line, or Puma v5 and above will fail with an error.

Here is an example of daemonizing via the config file shown above, and using the regular puma binary:

Note that using this method you can decide whether to daemonize or not by passing true or false to the daemonize method.

If you prefer to make a decision whether to daemonize or not on the command line, you only have to make one chance: replace puma with pumad.

If you replace puma with pumad, you no longer need to pass any additional command line flag (-d and --daemonize) to daemonize. You can continue passing them or you can remove them (these flags are stripped out before ARGV is passed onto Puma’s CLI parser.)

As you can see, at the end it says "Daemonizing".

If you start puma this way, you can still specify daemonize(false) in the configuration file to turn it off, but the default is to daemonize. Also, if you start with pumad you do not need to include require 'puma/daemon' in your configuration file, as the pumad binary loads all dependencies prior to parsing the config.