example.yml

# Reference config showing every available option (YAML format).
#
# NOT a runnable config: commands, paths, and hosts are illustrative
# placeholders. Use it as a lookup reference; copy what you need.
# The test in this folder keeps it honest: the file must pass the real
# config loader, and every option key the parser knows must appear here.

# Capture child stdout/stderr through gopherd (default: false).
# false: children write directly to the container's stdout/stderr — zero
#        supervision overhead, but prefixes, `gopherd logs`, and log-targets
#        are unavailable for that service.
# true:  gopherd pipes and processes output (prefixes, logs command,
#        log-targets, rotation).
# Can be overridden per process.
# log-capture: true

# Global log prefix format (space-separated tokens, applied in order).
# Only applied when log-capture is true.
# Tokens: "timestamp" (UTC timestamp), "service" ([name] tag).
# Examples:
#   "service timestamp"  — [app] 2021-05-13T03:16:51.001Z line  (default)
#   "timestamp service"  — 2021-05-13T03:16:51.001Z [app] line
#   "timestamp"          — timestamp only, no service name
#   "service"            — service name only, no timestamp
#   "none"               — no prefix at all (raw output)
# Omit or leave empty to use the default ("service timestamp").
# Can be overridden per process.
# prefix: "service timestamp"

# Global default for per-service export-socket (default: false).
# When true, each service's environment gets GOPHERD_SOCKET pointing at the
# daemon's control socket, so client commands work from inside services.
# export-socket: false

# Suppress the ASCII logo on daemon startup (default: false).
# no-logo: false

# Shutdown ordering strategy (default: reverse-dep).
#   reverse-dep:   dependents stop first, then dependencies (safest default)
#   dep:           dependencies stop first, then dependents (drain through proxy)
#   simultaneous:  all services stop concurrently (fastest)
# shutdown-order: reverse-dep

# Signals that trigger gopherd's own graceful shutdown. When unset,
# defaults to [SIGTERM, SIGINT]. SIGKILL and SIGSTOP are rejected at
# load — they cannot be caught by a userspace handler.
# init-stop-signal: [SIGTERM, SIGINT]

# Subreaper mode: re-parent orphaned descendants to gopherd so its reap
# loop collects them. Only needed when gopherd is NOT PID 1 (e.g. inside
# docker exec, a k8s sidecar, or nested init). Linux-only.
# subreaper: true

# Control socket for runtime service management.
# Use `gopherd stats` to view service and check statistics.
control:
  socket: /run/gopherd.sock
  # socket-mode: "0660"                  # octal file mode (default: 0600, owner-only)

# --- Processes ---
processes:
  # Oneshot: runs once before dependents start.
  - name: init-permissions
    command: /bin/sh
    args: ["-c", "chown app:app /data && chmod 750 /data"]
    startup: oneshot
    startup-timeout: 30s                 # kill the oneshot if it hangs past this
    # File conditions gate every start attempt (absolute paths; symlinks
    # followed). Unmet: the start is skipped and counts as success.
    # condition-file-exists: /data/enable  # run only if the path exists
    # condition-file-missing: /data/done   # run only if the path does not exist
    on-failure: ignore
    working-dir: /
    user: root
    group: root

  # Scheduled: runs oneshot-style at every matching cron minute. Never runs
  # at boot, takes no exit actions (the next tick is the retry), and cannot
  # participate in startup ordering (after/before/requires). schedule also
  # works with startup: disabled — gate via "{{.ENABLE_BACKUP:-disabled}}".
  - name: nightly-backup
    command: /usr/local/bin/backup.sh
    startup: scheduled
    schedule: "0 3 * * *"                # min hour day-of-month month day-of-week
    startup-timeout: 30m                 # stop the run if it exceeds this (optional)

  # Main application with all options.
  - name: app
    command: /usr/local/bin/myapp
    # {{.VAR}} expands to env value ("" if unset). {{.VAR:-default}} falls
    # back to the literal default text when VAR is unset or empty.
    args: ["--config", "/etc/app.conf", "--verbose", "-m", "{{.MEMLIMIT}}", "--threads", "{{cpu}}", "--log-level={{.LOG_LEVEL:-info}}"]
    # use-entrypoint-args: true          # append docker run args to this service (one service only)
    dotenv: /etc/app.env                 # load KEY=value env vars from file
    # dotenv-follow: true                # permit symlinked dotenv file (K8s ..data/ mounts)
    working-dir: /app
    user: app
    group: app
    # user-id: 1000
    # group-id: 1000
    # strict-groups: true                # drop the user's supplementary groups when group is set
    startup: enabled                     # enabled (default), disabled, oneshot, or scheduled
    stop-signal: SIGTERM                 # signal sent on shutdown (default: SIGTERM)
    kill-delay: 30s                      # grace period before SIGKILL (default: 10s)
    on-success: restart                  # restart|shutdown|success-shutdown|failure-shutdown|ignore
    on-failure: restart
    backoff-delay: 500ms                 # initial restart delay (default: 500ms)
    backoff-factor: 2.0                  # delay multiplier per attempt (default: 2.0)
    backoff-limit: 30s                   # max restart delay (default: 30s)
    after: [init-permissions]            # start after these services
    # before: [other]                    # start before these services
    requires: [init-permissions]         # hard dependencies (failure cascades)
    ready-check: app-http                # block dependents until this check passes
    ready-timeout: 60s                   # max wait for ready check (default: 60s)
    # sd-notify: true                    # systemd sd_notify: dependents wait for READY=1 on $NOTIFY_SOCKET
    # sd-notify-timeout: 30s             # max wait for READY=1 after spawn (default: 60s)
    # parent-death-signal: SIGTERM       # kernel delivers this signal to the child when gopherd dies (Linux)
    # exit-code-map:                     # remap observed exit codes before on-success/on-failure + propagation
    #   SIGTERM: 0                       #   SIGTERM-induced exit (shell code 143) → success
    #   SIGKILL: 0                       #   SIGKILL-induced exit (shell code 137) → success
    #   42: 0                            #   integer exit codes also accepted
    # signal-rewrite:                    # opt in to signal forwarding; keys/values are signal names
    #   USR1: HUP                        #   forward a received SIGUSR1 as SIGHUP to this service
    #   USR2: USR2                       #   forward a received SIGUSR2 as-is
    # Keys may not be SIGHUP or any signal in init-stop-signal — those
    # are consumed by gopherd for reload/shutdown and never reach this
    # forwarding branch. Invalid configs are rejected at load.
    # prefix: "service"                  # per-process prefix override (see global prefix)
    # pass-env: true                     # opt in to inheriting gopherd's OS env (default: false)
    # log-capture: true                  # capture output through gopherd (see global log-capture)
    # export-socket: true                # set GOPHERD_SOCKET in this child's env (see global export-socket)
    # remove-env:                        # strip these keys from the final child env
    #   - DB_PASSWORD                    #   (useful for shared dotenv files)
    #   - AWS_SECRET_ACCESS_KEY
    environment:
      DB_HOST: localhost
      DB_PORT: "5432"
      LOG_LEVEL: info
      LD_PRELOAD: /usr/local/lib/libwrapper.so
      GOMAXPROCS: "{{cpu}}"
      REGION: "{{.REGION:-us-east-1}}"   # env-var default syntax
      # File-inclusion template: read a Docker/K8s secret file at start time.
      # `trim` strips the trailing newline that most secret mounts include.
      # `:-default` falls back when the file does not exist.
      # DB_PASSWORD: '{{file "/run/secrets/db_password" trim}}'
      # LICENSE: '{{file "/etc/license.key":-no-license}}'
    on-check-failure:
      app-http: restart                  # action when named check breaches threshold
      db-tcp: shutdown

  # Sidecar: depends on app being ready.
  - name: sidecar
    command: /usr/local/bin/sidecar
    after: [app]
    on-success: ignore
    on-failure: restart
    backoff-delay: 1s
    backoff-factor: 1.5
    backoff-limit: 60s

  # Disabled: defined but not auto-started (start via control socket).
  - name: debug-tool
    command: /usr/local/bin/debug
    startup: disabled

  # Env-var gated: auto-start only when START_METRICS is set to a valid
  # startup value (e.g. "enabled" or "oneshot"). If unset/empty, the service
  # is "disabled" and can still be started manually via the control socket.
  - name: metrics-exporter
    command: /usr/local/bin/metrics-exporter
    startup: "{{.START_METRICS}}"

# --- Health checks ---
checks:
  # HTTP health check.
  app-http:
    http:
      url: http://localhost:8080/healthz
    period: 10s
    timeout: 3s
    threshold: 3
    initial-delay: 15s                   # wait before first check (default: 1x period)

  # HTTP health check over Unix socket.
  app-unix:
    http:
      url: http://localhost/health
      socket: /var/run/app/health.sock
    period: 5s
    timeout: 2s
    threshold: 3
    initial-delay: 10s

  # TCP health check.
  db-tcp:
    tcp:
      host: localhost
      port: 5432
    period: 5s
    timeout: 2s
    threshold: 5

  # Exec health check.
  custom-script:
    exec:
      command: /usr/local/bin/healthcheck
      args: ["--deep"]
    period: 30s
    timeout: 10s
    threshold: 2

# --- Log targets ---
log-targets:
  # Forward app logs to remote syslog.
  remote-syslog:
    type: syslog
    location: udp://logs.example.com:514
    services: [app, sidecar]             # only forward these (empty = all)
    labels:
      env: production
      cluster: us-east-1

  # Forward all logs to a second syslog.
  all-logs:
    type: syslog
    location: tcp://audit.example.com:514
    # services omitted = all services
    labels:
      purpose: audit

  # Write app logs to a file with size-triggered rotation.
  app-file:
    type: file
    location: /var/log/app.log
    services: [app]
    max-size: 10MiB                      # rotate when file would exceed this
    max-files: 5                         # keep app.log.1 ... app.log.5
    compress: true                       # gzip rotated files (.1.gz, .2.gz, ...)