Restarts

• Send the puma process the signal (rolling restart, cluster mode only)

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 process monitor (see below) when using it in production.

But beware, hot restart does not mean that the incoming requests won’t hang for multiple seconds while your new code has not fully deployed. If you need a zero downtime and zero hanging requests deploy, you must use phased restart.

When you run pumactl phased-restart, Puma kills workers one-by-one, meaning that at least another worker is still available to serve requests, which lead to zero hanging requests (yay!).

If you perform a lot of database migrations, you probably should not use phased restart and use a normal/hot restart instead (pumactl restart). That way, no code is shared while deploying (in that case, might help for quicker deployment, see “Clustered Mode” in the README).

If your symlink releases into a common working directory (i.e., /current from Capistrano), Puma won’t pick up your new changes when running phased restarts without additional configuration. You should set your working directory within Puma’s config to specify the directory it should use. This is a change from earlier versions of Puma (< 2.15) that would infer the directory for you.

You should place code to close global log files, redis connections, etc. in this block so that their file descriptors don’t leak into the restarted process. Failure to do so will result in slowly running out of descriptors and eventually obscure crashes as the server is restarted many times.