Skip to main content
← Back to list
01Issue
FeatureClosedSwamp CLIPublic
Assigneeshammz

Relationships

#2691 Docs: run swamp under an init in the worker-fleet guides

Opened by hammz · 9/29/2026

What changed

swamp-club#2652: swamp running as PID 1 in a container never reaps the processes that steps leave behind. Linux re-parents orphans to PID 1, and swamp only waits on children it spawned itself, so they stay zombies until the container exits. Zombies also keep a killed step's process group looking alive, so every cancel waits the full 3 s grace.

The official image now starts swamp as /tini -s -- swamp, and swamp serve and swamp worker connect log a warning when they run as PID 1 on Linux.

Manual pages that need updating

The worker-fleet guides never use the official image, so the image fix does not reach them, and the new warning fires for anyone who follows them.

  • content/manual/how-to/worker-fleets/docker.md: the custom Debian image ends with ENTRYPOINT ["swamp"]. Install tini (apt-get install -y tini) and use ENTRYPOINT ["/usr/bin/tini", "-s", "--", "swamp"], or tell readers to run it with docker run --init. Say why in one sentence.
  • content/manual/how-to/worker-fleets/docker-compose.md: add init: true to the worker service (or rely on the tini entrypoint above).
  • content/manual/how-to/worker-fleets/kubernetes.md: both manifests set command: ["swamp", "worker", "connect"], which replaces the image entrypoint. Kubernetes has no --init, so the image must carry tini and the manifests should use args: ["worker", "connect"] instead of command:.

content/manual/how-to/swamp-serve/deploy-on-kubernetes.md uses the official image with args: only, so it is fixed automatically and needs no change.

02Bog Flow
✓OPEN✓TRIAGED✓IN PROGRESS◉CLOSED+ 1 MOREASSIGNED+ 8 MOREREVIEW+ 4 MOREVERIFICATION_PASSED

Closed

9/29/2026, 4:43:58 PM

No activity in this phase yet.

03Sludge Pulse
hammz assigned hammz9/29/2026, 3:12:48 PM
Editable. Press Enter to edit.

hammz commented 9/29/2026, 4:43:58 PM

Shipped in swamp-club#1262 (merged as 9829d910).

The worker-fleet Dockerfile now installs tini and uses ENTRYPOINT ["/usr/bin/tini", "-s", "--", "swamp"]. The Compose guide names that image as a prerequisite and its YAML is unchanged, because command: only overrides CMD. Every Kubernetes manifest that set command: [swamp, ...] now passes args: instead, so the image entrypoint stays in place: worker-fleets/kubernetes.md (Deployment and Job), remote-execution.md (Job) and swamp-serve/use-a-config-file.md (serve Deployment, which now names swampclub/swamp:latest). The last two weren't in this issue but had the same bypass. The remote-execution.md docker run example also no longer repeats swamp.

Verified on swamp 20260929.151817.0 against a local swamp serve:

  • Old image: logs the PID 1 warning, and an orphaned step sleep is left as a zombie under PID 1.
  • New image: no warning, PID 1 is tini, and the orphan is reaped.
  • docker stop mid-step: the step still drains and the container exits 0.
  • --max-dispatches 1: the worker exits 0.
  • command: form (entrypoint override): brings the warning back.

The guides' orchestrator setup is separately out of date with current swamp (--admins, swamp access token mint). That's tracked in #2701.

Sign in to post a ripple.