README.md

gopherd Documentation Examples

Each subfolder is a self-contained, CI-tested example: a runnable example.yml, a README.md explaining it, and a Go test that proves the documented behavior. Examples use realistic placeholder commands (e.g. /usr/local/bin/myapp); the tests substitute runnable stand-ins so the same config is both copy-paste documentation and a live test.

Run all example tests:

go test ./documentation/...

Basics

• minimal — single process supervised by gopherd
• multi-service — several independent services
• environment-passthrough — pass-env forwarding

Ordering & lifecycle

• dependencies — after: start ordering
• oneshot — run-to-completion startup tasks
• shutdown-order — shutdown-order strategies
• startup-timeout — kill hung oneshots

Health & readiness

• health-check-http — HTTP health check
• health-check-tcp — TCP connect check
• health-check-exec — command-based check
• ready-gate — block dependents until a check passes
• sd-notify — systemd READY=1 readiness gate

Signals & exit

• signal-rewrite — map forwarded signals
• exit-code-map — remap child exit codes
• init-stop-signal — which signals stop gopherd

Templating

• env-templates — {{.VAR}} / {{.VAR:-default}}
• service-gating — enable a service via env var (startup: "{{.START_X}}")
• cpu-template — {{cpu EXPR}}
• cpu-headroom — {{cpu 100% - 1}} reserve a core
• mem-template — {{mem EXPR}}
• mem-headroom — {{mem 100% - 64MiB}} reserve memory
• mem-golang-template — GOMEMLIMIT for a Go app
• file-inclusion — {{file "/path"}}

Logging

• log-capture — opt-in output capture vs direct FD passthrough (default)
• log-prefix — per-line timestamp + service prefix
• log-file-rotation — size-based file rotation
• syslog-target — forward logs to syslog

Runtime control

• control-socket — start/stop/status over the socket
• subreaper — PR_SET_CHILD_SUBREAPER for non-PID-1 use