Feature: Container mode (--pid1) for multi-process Docker images

[joeblew999]

Summary

Pitchfork is already the best cross-platform Rust daemon manager available. With a small --container / --pid1 flag it could also replace s6-overlay as the go-to supervisor inside multi-process Docker images — something no other Rust project currently does well.

What's already there

The groundwork is solid:

• depends for ordered startup
• ready.http / ready.delay / ready_cmd for true readiness (better UX than s6's fd-based protocol)
• setsid() + killpg() for process-group shutdown
• Cross-platform (macOS, Linux, Windows) — unique in this space

What's missing for container/PID1 use

When pitchfork runs as PID 1 inside a Docker container two things break:

1. Zombie reaping
PID 1 must call waitpid(-1, WNOHANG) on every SIGCHLD to reap orphaned processes (children whose parent exited before them). Without this, zombie entries accumulate in the process table indefinitely.

2. SIGTERM forwarding on docker stop
Docker sends SIGTERM to PID 1. Currently that kills pitchfork without giving daemons a chance to shut down cleanly. In container mode, SIGTERM to PID 1 should trigger the normal graceful shutdown sequence (SIGTERM to process groups → grace period → SIGKILL).

Proposed API

[supervisor]
container = true

Or as a CLI flag: pitchfork supervisor run --container

When container = true:

• Install SIGCHLD handler that reaps all children, not just direct ones
• Route SIGTERM/SIGINT to the graceful shutdown sequence
• Exit with the exit code of a designated main daemon

Real-world use case

United Manufacturing Hub (open-source Industrial IoT platform used in production by Böllhoff, HiPP, Edeka) runs a single Docker container with three processes: a Go agent, Benthos streaming engine, and Redpanda broker. They currently use s6-overlay in C. Pitchfork with container mode would be a drop-in replacement with far better DX and cross-platform support.

Implementation notes

The nix crate already has everything needed: waitpid, WaitPidFlag, Signal, sigaction. Core addition:

// On SIGCHLD, reap all available children
loop {
    match waitpid(None, Some(WaitPidFlag::WNOHANG)) {
        Ok(WaitStatus::StillAlive) | Err(_) => break,
        Ok(_) => {}
    }
}

Plus routing SIGTERM through the existing graceful shutdown path.

Happy to help test or contribute a PR.

[gaojunran]

I think both [settings.supervisor.container] (in settings.toml) and pitchfork supervisor run --container can be added.

Docker sends SIGTERM to PID 1. Currently that kills pitchfork without giving daemons a chance to shut down cleanly. In container mode, SIGTERM to PID 1 should trigger the normal graceful shutdown sequence (SIGTERM to process groups → grace period → SIGKILL).

After a quick search I found that when pitchfork receives a SIGTERM, it'll gracefully shutdown all active daemons like below? (at least from the code) If the actual behaviour is not this, I'll dive into this to check out why.

async fn handle_signal(&self) {
    info!("received signal, stopping");
    self.close().await;
    exit(0)
} 

pub(crate) async fn close(&self) {
    for daemon in self.active_daemons().await {
        if daemon.id == pitchfork_id { continue; }
        if let Err(err) = self.stop(&daemon.id).await {
            error!("failed to stop daemon {daemon}: {err}");
        }
    }
    // ...
} 

Overall this is a great FR and I'll work on this later.