Skip to content

Commit bbeaf8c

Browse files
rosaclaude
andcommitted
Document how the Puma plugin behaves when the supervisor can't boot or exits
The plugin stops Puma when the supervisor fork dies, which surprised people whose queue database was unreachable at boot or blinked mid-run. Since #781 a transient outage no longer takes the supervisor down, but a database that's unreachable at boot still does, by design: the process manager is expected to restart Puma. Spell out both in the Puma plugin section. See #512. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CACej2M9mLVDwpE3Bk8V41
1 parent 93c5310 commit bbeaf8c

1 file changed

Lines changed: 2 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -822,6 +822,8 @@ that you set in production only. This is what Rails 8's default Puma config look
822822

823823
**Note**: phased restarts are not supported currently because the plugin requires [app preloading](https://github.com/puma/puma?tab=readme-ov-file#cluster-mode) to work.
824824

825+
The plugin ties the two processes together: if Puma goes away, the supervisor stops, and if the supervisor exits, the plugin stops Puma so that whatever manages Puma (systemd, Kamal, your container orchestrator...) restarts both. In particular, the queue database needs to be reachable when the supervisor boots, as it registers itself and cleans up after previous runs at that point; if it isn't, the supervisor exits, and Puma with it. Once running, a transient database outage doesn't bring the supervisor down: workers and dispatchers will fail and be replaced until the database is back, and then pick up where they left off.
826+
825827
### Running as a fork or asynchronously
826828

827829
By default, the Puma plugin will fork additional processes for each worker and dispatcher so that they run in different processes. This provides the best isolation and performance, but can have additional memory usage.

0 commit comments

Comments
 (0)