documentation

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/...

Reference

• all-options — every option in one commented config; not runnable, but CI-validated: it must pass the config loader and mention every option key the parser reads

Basics

• minimal — single process supervised by gopherd
• multi-service — several independent services
• environment-passthrough — pass-env forwarding
• remove-env — strip keys from a child's environment
• entrypoint-args — use-entrypoint-args and passthrough exec
• block-style-args — args: as a block YAML list
• block-scalars — multi-line values via YAML literal block scalars (|)

Ordering & lifecycle

• dependencies — after: start ordering
• requires — hard dependencies with failure coupling
• stop-signal — per-service stop-signal + kill-delay escalation
• oneshot — run-to-completion startup tasks
• scheduled — cron-scheduled oneshot-style runs
• service-conditions — gate a start on a file existing or missing
• shutdown-order — shutdown-order strategies
• startup-timeout — kill hung oneshots
• restart-backoff — on-failure: restart with exponential backoff

Health & readiness

• health-check-http — HTTP health check
• health-check-tcp — TCP connect check
• health-check-exec — command-based check
• health-check-http-unix — HTTP check over a Unix socket
• on-check-failure — check-driven restart (self-healing)
• 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}}
• dotenv — KEY=value file into templates and child env
• 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
• log-streaming — logs history and logs -f live follow

Runtime control

• control-socket — start/stop/status over the socket
• export-socket — client commands from inside services
• hot-reload — gopherd reload / SIGHUP config reconcile
• subreaper — PR_SET_CHILD_SUBREAPER for non-PID-1 use