Guide
Health checks for a Go service
A health check is the gate between a started process and a version that serves traffic. The stronger the signal, the less a deploy relies on luck.
Start with a readiness endpoint
A readiness endpoint should answer whether this instance can serve requests right now: dependencies reachable, migrations applied, listeners bound. Keep it cheap and deterministic; it is called on every deploy and on the monitoring interval.
In Go, that is usually a small handler that checks the pieces the service cannot run without and returns 200 only when they pass.
Tiers and modes
Phelix uses a tiered model. Tier 1 is an explicit path returning 2xx. Tier 2 is any HTTP response on the port. Tier 3 is a TCP accept or a live PID. Each tier is a weaker statement than the one above it.
The mode flag makes the fallback explicit: auto picks the strongest supported tier, http requires an HTTP check, tcp-only skips HTTP, and none treats PID existence as the only signal.
- Tier 1: HTTP 2xx on the path you configured
- Tier 2: any HTTP response, even 404 or 500
- Tier 3: TCP port accepts, or the process still exists
What health does and does not prove
During a deploy, an unhealthy candidate stays off traffic, and the current version keeps serving. After deploy, repeated endpoint failures can trigger bounded restart attempts with an attempt cap; if restoration fails, Phelix records a degraded state for manual intervention.
A passing check reduces risk; it does not prove every behavior is correct. That is why a retained version and a one-command rollback matter as much as the check itself.
Frequently asked questions
Short answers; the docs go deeper.
What should a Go health check endpoint return?
A readiness endpoint should verify the dependencies the service cannot run without and return HTTP 2xx only when it can serve requests. Avoid expensive checks on a path that runs on every deploy and monitoring interval.
What happens when a health check fails during a deploy?
The candidate stays off traffic and the deploy aborts, leaving the current version serving. Repeated failures after deploy can trigger bounded restarts; an instance that cannot recover is marked degraded.
One binary between git push and production.
Install the CLI, verify the host, and follow the quick start to build your first application.