Skip to content

Docker Healthchecks

hxEASM Docker Compose services expose real healthchecks so Docker can report whether containers are operational, not only whether their main process still exists.

Health status is visible with:

docker compose ps

For detailed container health state:

docker inspect --format='{{json .State.Health}}' <container>

Service Checks

Service Check Interval Timeout Retries Start Period
frontend GET http://localhost:3000/health served by Nginx 15s 5s 3 10s
api GET http://localhost:8080/health/ready 15s 5s 5 20s
worker ./worker healthcheck 30s 10s 5 60s
postgres pg_isready -U easm -d easm 5s 5s 10 5s
redis redis-cli ping 5s 3s 5 5s
minio GET http://localhost:9000/minio/health/ready 10s 5s 5 10s

API Health Endpoints

The API exposes unauthenticated health endpoints outside /api/v1.

GET /health/live

Returns 200 when the API process is alive and serving HTTP requests.

{"status":"ok"}

GET /health/ready

Returns 200 only when the API can reach the dependencies required for normal operation:

  • PostgreSQL
  • Redis
  • file storage bucket through S3/MinIO

If readiness fails, the API returns 503:

{"status":"not_ready"}

The response intentionally does not expose DSNs, credentials, API keys, stack traces, or detailed dependency errors. Dependency failures are logged server-side.

GET /health remains a simple compatibility liveness endpoint and returns {"status":"ok"}.

Frontend Health

Frontend health is served directly by Nginx at:

GET /health

This endpoint does not depend on React SPA routing and does not require backend API availability. It is outside the Basic Auth-protected SPA location so Docker can check it locally without credentials. This does not weaken Basic Auth for the application shell.

Worker Health

The worker does not expose HTTP. Its Docker healthcheck runs:

./worker healthcheck

The subcommand verifies that the worker container can:

  • load runtime configuration
  • connect to PostgreSQL
  • connect to Redis
  • verify the S3/MinIO file storage bucket

It does not install scanner tools, dequeue Redis jobs, start scans, run plugins, or run the scheduler.

Compose Dependencies

Docker Compose waits for real dependency health where startup requires it:

  • api waits for healthy postgres, redis, and minio
  • worker waits for healthy postgres, redis, and minio

The frontend does not wait for API health. Nginx can serve the SPA while the API is still starting, and API requests will recover when the backend becomes available.

Restart Behavior

Healthchecks continue running after container restart. A normal restart should move through:

starting -> healthy

Validate with:

docker compose restart
docker compose ps

Important Limitation

Docker Compose restart policies do not automatically restart a container only because it becomes unhealthy.

Health status is useful for:

  • dependency ordering
  • monitoring
  • external orchestration
  • alerting

Automatic restart-on-unhealthy requires an external watchdog or orchestrator and is not implemented by hxEASM Compose.