Skip to main content

​
Overview

The gomodel binary exposes a small set of command-line flags for operational tasks. Flags accept both single-dash (-flag) and double-dash (--flag) forms; the examples below use the long form.

​
Version

Print the build version and exit:

​
Health probe

--health makes the binary act as a health-check client: it loads the same configuration as the server, requests the local /health endpoint, and exits.
  • Exits 0 when the endpoint returns HTTP 200 with {"status":"ok"}.
  • Exits non-zero otherwise (connection refused, non-200 status, or any other status value).
The probe always targets the loopback interface (127.0.0.1) since it runs inside the same container as the server, but it derives the PORT and BASE_PATH from configuration instead of hardcoding 8080 and /health. Bound the request with --health-timeout:

​
Docker HEALTHCHECK

Because the probe is built into the binary, container images can report health without shipping curl or wget — useful for minimal/distroless runtimes. The official image wires it up automatically:
Orchestrators (Docker, Compose, Kubernetes) can then detect and restart an unhealthy gateway.

​
Readiness probe

--ready probes /health/ready, which reports whether the instance should receive traffic. Unlike liveness, readiness checks the dependencies the gateway owns:
  • Storage is required. If the backend (SQLite/PostgreSQL/MongoDB) is unreachable, readiness reports not_ready (HTTP 503).
  • Redis exact cache (when configured) is a performance optimization. If it is unreachable, readiness reports degraded but stays HTTP 200 — the gateway still serves requests.
Upstream provider reachability is deliberately excluded: a provider outage must not pull a healthy gateway out of rotation.
  • Exits 0 when the endpoint returns HTTP 200 (ready or degraded).
  • Exits non-zero on not_ready (HTTP 503), connection refused, or an unexpected status value.
Liveness (--health) is the right signal for a Docker HEALTHCHECK (restart on crash). Readiness (/health/ready) is the right signal for a Kubernetes readinessProbe (gate traffic) — point it at the HTTP endpoint directly or run gomodel --ready as an exec probe. Keep --ready-timeout larger than the server’s internal per-dependency probe timeout (2s) so a slow backend returns a clean not_ready instead of the client timing out first.
Last modified on August 1, 2026