Health and status

One endpoint and one docker command tell you whether the instance is up and which version is running.

1. curl -s http://localhost:8088/api/v1/healthz answers ok: true while the api is serving.
2. docker compose ps shows the container state. running (healthy) is normal.
3. Stuck in health: starting, unhealthy, or restarting after an update? Almost always a failed migration. Read docker compose logs --tail=100 api, then Rollback.

The health endpoint

Call it, no login needed:

curl -s http://localhost:8088/api/v1/healthz

{
  "ok": true,
  "service": "cobblr-api",
  "env": "production",
  "deploy_env": "production",
  "build_sha": "a1b2c3d",
  "time": "2026-07-11T15:04:05.000Z"
}

• ok: true means the api is up and serving.
• deploy_env is the label your instance shows in its environment chip.
• build_sha is the running build. The app polls it so an open tab can notice it is behind after you update and offer a refresh. It is also how you confirm, from the outside, which version answered.
• Safe for an uptime checker. The endpoint is mounted ahead of authentication on purpose, so a health check is never gated behind a login.

The container healthcheck

Read the current state with:

docker compose ps

You will see one of:

• running (healthy): up and passing checks. Normal.
• running (health: starting): inside the grace period, still booting. Give it up to a minute after an update.
• restarting or running (unhealthy): the api is not coming up.

How the healthcheck is timed

The api container has a built-in healthcheck that calls the same endpoint every 30 seconds. It gives startup a 60-second grace period (start_period) before a failing check counts against it, because the first boot after an update runs the database migrations and loads modules before the api listens.

What a stuck deploy looks like

After docker compose pull && docker compose up -d:

1. A healthy update settles to running (healthy) within a minute or so.

2. A stuck one stays in health: starting and then flips to unhealthy, or the container sits in restarting.

3. Read the reason in the logs. A failed migration names itself in that output:

   docker compose logs --tail=100 api

4. Step back to the previous version: see Rollback.

That pattern almost always means a migration failed on the first boot, which crashes startup by design rather than serve a half-migrated database. For reading logs in general, see Logs.