Skip to main content

Operations

identsphere doctor​

A preflight + health check for a self-hosted install. It validates the things that silently break a deployment and exits non-zero if a hard requirement is missing (handy in CI or a container healthcheck).

docker run --rm --entrypoint /identsphere ghcr.io/identsphere/server:latest \
  doctor --database-url "$DATABASE_URL"

It checks:

  • IDENTSPHERE_JWT_SECRET / IDENTSPHERE_PUBLIC_BASE_URL — required env set.
  • Database — connectivity.
  • Migrations — applied (else: run identsphere migrate up).
  • Platform owner — at least one exists (else: set IDENTSPHERE_INITIAL_OWNER_EMAIL or run identsphere admin grant).
  • IDENTSPHERE_CONFIG_KEY — whether dashboard secret storage is enabled.
  • Providers — which are enabled.

Hard failures (missing required env, no DB, un-applied migrations) → exit code 1.

Provider config health​

The Integrations page is the source of truth for provider status. Watch for the degraded badge: it means a provider has a stored secret that the server can't currently decrypt (usually the master key was rotated away) — the server falls back to env config rather than failing. Re-save the secret to fix. Decrypt failures and env-fallbacks are also logged at WARN.

Health endpoints​

  • GET /healthz — liveness.
  • GET /readyz — readiness.
  • GET /metrics — Prometheus exposition.

Backups​

Back up two things beyond your database:

  • IDENTSPHERE_JWT_SECRET — losing it invalidates all sessions.
  • IDENTSPHERE_CONFIG_KEY — losing it means re-entering dashboard provider secrets (see Secrets & encryption).