Docs Self-hosting & operations
Self-hosting & operations
Check your installation is healthy
One command answers "is Kumo.io healthy?", three HTTP endpoints answer it for load balancers and monitors, and kumo deployment doctor checks the infrastructure around it.
kumo doctor
kumo doctor runs Kumo.io's health checks against the installation's database and prints a report. On the single container:
docker exec kumo kumo doctorIt checks:
- the build — the version that is running,
- the database — that Kumo.io can reach it,
- the license — whether one is installed, and when it expires,
- login readiness — whether anyone can actually log in to the accounts in the database.
The first line says Kumo.io doctor: healthy or Kumo.io doctor: UNHEALTHY. Each finding after it shows a severity (INFO, WARN, ERROR or FATAL), the part it is about, a summary and a code, and often a → line saying what to do.
| Option | What it does |
|---|---|
--require-login | Treat "nobody can log in" as an error instead of a warning — a check that the installation is usable, not just running |
--format json | Print the report as JSON |
kumo doctor exits 0 when healthy and 1 when any finding is an error or worse, so you can use it in scripts and readiness checks.
HTTP health endpoints
These need no login and are not rate-limited. On the single container they are on port 9500:
| Endpoint | Answers |
|---|---|
GET /v1/healthz | Is the API process up? Always {"status":"ok"} while it is running; it checks nothing else |
GET /v1/readyz | Is it ready for traffic? 200 with {"status":"ok"} when the database and license checks pass, 503 with "status":"not_ready" and the failing checks when they don't |
GET /v1/version | Which version is running |
curl -fsS http://localhost:9500/v1/readyzPoint load-balancer health checks at /v1/readyz, and liveness checks at /v1/healthz.
The admin API has its own readiness endpoint, /v1/admin/readyz, and a full report at /v1/admin/diagnostics, which needs the admin credential:
curl -fsS -H "Authorization: Bearer <admin-token>" \
http://localhost:9500/v1/admin/diagnosticsThe startup page
/setup on the installation lists each startup step and whether it passed. If Kumo.io could not start, the page says Kumo.io could not start and gives a What to do note for each failed step. It is the first place to look when the app won't load.
kumo deployment doctor
For installations managed by kumo deployment, check the infrastructure as well as the product:
kumo deployment doctor --file <spec>
kumo deployment status --file <spec>doctor checks the target (Docker, or your AWS account), the release image, the topology and the running roles. It is read-only and never repairs anything. It exits 3 when a check is blocked. status gives a short summary of health and convergence, with the addresses to open.
The database schema
To confirm the schema matches the running version, run kumo db migrate --validate — it exits 1 when migrations are pending or have drifted. See Migrations.
Still stuck
Build a support bundle — it includes the same diagnostics report, with secrets redacted — and send it to support.