Health checks

Tell HostStack which URL proves your app is up. It uses that URL to decide when a new deploy may take traffic, and keeps probing it afterwards so you hear about a service that stops answering.

What a health check does

A web or private service's health check does two separate jobs:

Readiness, during a deploy. The new container starts next to the old one. HostStack sends it an HTTP GET every two seconds until it answers with a healthy status, and only then moves traffic across. If it never does within the grace period, the new container is removed and the old one keeps serving.
Monitoring, after the deploy. The running container is probed on an interval. Three failures in a row raise an alert; the next good answer clears it.

Every probe is plain HTTP to the container's own address on the port in PORT (3000 unless you change the service's port) — never through your public domain, and never over HTTPS.

Set a health-check path

Without a path, HostStack probes /. That works for most apps, but a dedicated route that returns 200 once the app can really serve —/health, /api/health — gives you a stricter check and turns on edge-level health checking too (see How a probe is judged).

In the dashboard, open the service's Settings, then the Health Check tab, fill in Health Check Path and click Save Health Check Settings. The new values apply from the next deploy.

hoststack services update svc_... \
  --health-check-path /health \
  --health-check-interval 30 \
  --health-check-timeout 5 \
  --health-check-grace 180

// The path lives on the service…
await hs.services.update(teamId, 'svc_...', { healthCheckPath: '/health' });

// …the timings on its config.
await hs.services.updateConfig(teamId, 'svc_...', {
  healthCheckInterval: 30,
  healthCheckTimeout: 5,
  healthCheckGracePeriodSec: 180,
});

Set the health check path of my "web" service to /health
and give it a 180-second grace period.

services:
  web:
    type: web_service
    healthCheck:
      path: /health
      interval: 30   # seconds
      timeout: 5     # seconds

A hoststack.yaml in the repository wins over the dashboard for the deploys it is part of; it can set the path, interval and timeout, but not the grace period. See Infrastructure as code.

Settings

healthCheckEnabled

boolean

Dashboard: Enable Health Checks. CLI: --health-check / --no-health-check. Turning it off replaces the HTTP readiness probe with the container check described under Services that don't serve HTTP, and stops ongoing monitoring.

Default: true for web and private services

healthCheckPath

string | null

Dashboard: Health Check Path. CLI: --health-check-path. Up to 500 characters. Pass an empty string to clear it.

Default: none (probes /)

healthCheckInterval

seconds, 5–300

Dashboard: Check Interval (seconds). CLI: --health-check-interval. How often the ongoing probe runs.

Default: 30

healthCheckTimeout

seconds, 1–60

Dashboard: Timeout (seconds), which accepts up to 30. CLI: --health-check-timeout. How long one ongoing probe may take. Readiness probes during a deploy always use a fixed 3-second timeout.

Default: 5

healthCheckGracePeriodSec

seconds, 1–1800

Dashboard: Initial Grace Period (seconds). CLI: --health-check-grace. The whole time a new container has to become ready during a deploy. Raise it for apps that run migrations or warm caches before they listen.

Default: 120

How a probe is judged

Probe	Healthy	Unhealthy
Readiness (deploy)	Any `2xx` or `3xx`. Redirects are not followed.	`4xx`, `5xx`, or no answer, until the grace period runs out.
Ongoing, with a path	`2xx` or `3xx`.	`4xx`, `5xx`, or no answer within the timeout.
Ongoing, without a path	Any HTTP response at all on `/`.	No answer within the timeout.
Edge (Traefik), with a path only	`2xx` or `3xx`, probed every 5 seconds.	A failing replica is taken out of the load balancer until it answers again.

Static sites are the exception: their readiness check wants an exact 200 for the site's index.html.

When a check fails

During a deploy, a container that is not ready within the grace period is stopped and removed, and the previous container keeps serving. The deploy fails early, without waiting out the grace period, if the new container restarts three times while HostStack waits for it.

After a deploy, three failed probes in a row send one Health check failing notification to the dashboard and to your alert channels, and record service.health_check_failed in the activity log. When the probe passes again you get Health check recovered and service.health_check_recovered.

A service on the recreate deploy strategy has no old container to fall back to: if the new one fails readiness, the service stays down until a deploy succeeds. See Deploying.

Services that don't serve HTTP

Background workers and cron jobs are created with health checks off, and you can turn them off on any service. HostStack then waits for the container to reach a steady state instead of probing it:

If the image defines a Dockerfile HEALTHCHECK, the deploy switches over once Docker reports it healthy, and fails if it reports unhealthy. The wait is capped by the grace period.
Without one, the container must stay up for 15 seconds without exiting or restarting.

With health checks on, a Dockerfile HEALTHCHECK plays no part in HostStack's decisions — the HTTP probe does.

Troubleshooting

the container never answered on port 3000: Nothing accepted a connection on PORT. Make the app listen on 0.0.0.0 — not 127.0.0.1 or localhost — on the port in the PORT variable. If it is listening, it is still booting: raise the grace period.
last response was HTTP 404 on /health: The app is up, but the path you set does not exist or needs authentication. Point the health-check path at a route that returns 2xx or 3xx without a login.
last response was HTTP 500 on /: The app answers but fails. Read the service's runtime logs for the error; a missing environment variable or an unreachable database is the usual cause.
Container crash-looped: The process exited three times before it ever answered. The runtime log shows why — often a crash on start-up, or a write to the read-only filesystem (see Container runtime).

Next steps

Was this page helpful?