Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Manual for Bouncer 0.5.7. Chapters state version and distribution limits. Source cdd3b59, site build 20 November 2026. Your server or app may run an earlier version.

On this page

Health checks

What to watch

CheckHowHealthy answer
Bouncer readinesscurl -s http://127.0.0.1:8080/v1/health on the server, or https://bouncer.example.com/v1/health from elsewhereHTTP 200 with "status":"ok" and your instance ID. From 0.5.6, backend_* with 503 means OpenBao isn't ready. From 0.5.7, database_unavailable with 503 means PostgreSQL isn't ready. A bare 502 means the proxy could not get an answer
The containersdocker compose psBoth services healthy
OpenBaocurl -s https://openbao.example.com:8443/v1/sys/healthHTTP 200 (initialised, unsealed and active)
BackupsThe newest file in your backup folder, and the backup timer's statusLess than about a day old
Disk spaceYour usual monitoringUnder 80% on the Docker volumes and OpenBao's data and audit volumes
OpenBao secret_id expiryThe date you noted at installRenew before it passes (Maintenance)

What Bouncer's health check does and doesn't tell you

GET /v1/health needs no credential. In 0.5.6, its 200 answer means the process is running and its OpenBao readiness check passed. From 0.5.7, it also checks PostgreSQL. Version 0.5.6 and earlier do not check the database. Earlier servers, such as 0.3.8, do not have the OpenBao readiness behaviour either.

A healthy answer does not prove every resource's role, secret path, SSH signer operation or push delivery works. Verify those separately with fake data. Readiness results can be cached; health is not a fresh issuance test. This example from our 0.5.0 test run shows the shape of the answer; newer servers add fields:

{"status":"ok","instance":{"id":"example-home","name":"Example home","url":"https://bouncer.example.com","contract":"bouncer.v1","version":"0.5.0+27","android_key_attestation":true,"credential_types":true},"server_time":"2026-11-15T06:28:31Z"}

With the database available, while OpenBao is sealed, can't be reached, or refuses the server's own login, the server stays up and answers 503 with backend_sealed, backend_unreachable or backend_auth_failed, and so does every other public call except revokes and cancels. When Bouncer is unavailable explains each one and who acts.

On health calls, Bouncer refreshes its OpenBao readiness check at most once every 5 seconds. It also checks OpenBao every minute on its own. Monitor OpenBao's /v1/sys/health as well, and alert when it isn't 200: it doesn't depend on Bouncer, and it tells "sealed" (503) from "not initialised" (501).

Database readiness from 0.5.7

From 0.5.7, Bouncer probes PostgreSQL with SELECT 1 on a separate connection, so a busy application connection pool does not itself fail the probe. Connecting and running the query share a one-second deadline. The result is cached for five seconds, so an outage or recovery can take until the next check to appear.

A failed probe returns 503 database_unavailable with Retry-After: 5. The server stays up and issues nothing while that readiness gate is closed. It notices database recovery on a later check without a restart. If both PostgreSQL and OpenBao are down, the database error comes first; after the database recovers, a remaining backend_* error becomes visible.

This handles a database outage under a running server. Starting the server still needs PostgreSQL to apply migrations and load state. The source builds tested before the 0.5.7 version bump still reported 0.5.6+33; check their source revision as well as their version.

Resource counts from 0.5.7

From 0.5.7, health can include two optional counts: unprovisioned_resources for definite token-resource gaps and provisioning_upgrade_needed for resources whose metadata needs the newer kit. The endpoint is unauthenticated, so anyone who can reach it can read these counts. It publishes no resource names or paths through those fields.

They are last-known counts, not fresh network probes. Successful resource checks are cached for 60 seconds and gaps for five; start-up, reload and periodic checks refresh them. Health can still be HTTP 200 while a resource is refused. Alert on a nonzero gap count and investigate with the preflight report. A nonzero provisioning_upgrade_needed count means you should apply the current role kit. It doesn't mean there's an outage, and it isn't a passed configuration check.

Provisioning changes have resource_provisioning_changed entries in the approval log and events naming the resource sent to its approvers only. Apps fetch those events by polling; there is no push notification for this event kind. OpenBao outages do not write false provisioning transitions. This was checked against the source for 0.5.7, and hasn't been run end to end.

The containers' own health checks

The compose file gives each container a health check, which Docker or Podman runs:

  • bouncer: GET /v1/health on the server's own address, every 30 seconds. It's unhealthy while OpenBao isn't ready and, from 0.5.7, while PostgreSQL isn't ready. Docker doesn't restart it for that; the server recovers after a seal, network or database outage once its dependencies are ready. A refused login needs repair; a login with unsafe powers needs a restart, and a replaced secret_id file needs the container recreated (Maintenance).
  • postgres: pg_isready, every 10 seconds, once PostgreSQL has finished its first-start setup.

Both containers use the restart policy unless-stopped, so a crash restarts them, but a container you stopped stays stopped.

With rootless Podman, the health checks run from systemd timers in your user session. Turn on lingering (sudo loginctl enable-linger $USER) so they keep running after you log out. Podman also doesn't start the stack after a reboot by itself: run podman-compose up -d again, or from a systemd user unit of your own.

Diagnose a database outage

In 0.5.6 and earlier, the Bouncer container can remain healthy and /v1/health can return 200 while PostgreSQL is stopped. In our test with fake data, a configured requester's bouncer resources then failed with HTTP 500 and an internal error. From 0.5.7, the failed readiness probe instead reports 503 database_unavailable. The diagnostic steps below apply to both.

From deploy/compose on the server, inspect both containers, including stopped ones, and their recent logs:

docker compose ps --all
docker compose logs --tail=100 bouncer postgres

In the ps output, check the postgres service's state and health. Older database failures appear as internal error with a database: cause. From 0.5.7, the readiness check logs the database isn't ready. PostgreSQL's log shows shutdowns and start-up failures. If it was stopped, start it:

docker compose up -d postgres

Keep the existing database volume: don't remove it or initialise a new database to get Bouncer working again.

If it is running but unhealthy, fix the cause in its log, such as a full disk or a permission error, then restart it:

docker compose restart postgres

Once PostgreSQL shows healthy, check that it accepts connections:

docker compose exec -u postgres postgres pg_isready --dbname=postgres

Check Bouncer's health again, then run bouncer resources from a client with a configured requester. That verifies a Bouncer operation using the database without reading a secret value. A successful pg_isready alone does not verify Bouncer's database login or query access. If the client still fails, inspect the Bouncer log for its database connection, socket or authentication error. For a changed password, follow Change the database password.

Logs

docker compose logs -f bouncer

The server logs at info by default (RUST_LOG in .env sets error, warn, info or debug). Logs rotate at 10 MB, 5 files per container. The log never holds a requester key, device token, pairing code, OpenBao token or secret value. Lines worth alerting on:

  • start-up failures (the server stops with a message saying what to fix);
  • the database isn't ready (from 0.5.7): PostgreSQL failed the readiness probe; the database is ready again records recovery;
  • the credential backend isn't ready: OpenBao is sealed, unreachable or refusing the server's login, and the server answers 503 until it's fixed (When Bouncer is unavailable);
  • resource isn't provisioned and resource provisioning is ready again (from 0.5.7): check the named resource and the health gap count;
  • role-kit upgrade needed for the provisioning check (from 0.5.7): apply the current kit and require preflight exit 0;
  • repeated revoke failures, which mean OpenBao isn't confirming revokes;
  • BOUNCER_WAIT_FOR_OPENBAO is ignored: remove that setting from .env (it no longer does anything).

How this was checked

The health answer above is the one our test server gave, with only the instance's name, ID and address changed. The test also checked both containers' health checks passed.

The database-readiness description was checked against the source. Automated availability tests cover an unavailable database, its recovery and an exhausted connection pool. The Compose smoke test stops and restarts PostgreSQL and checks that Bouncer did not restart. We haven't run this part ourselves.

This manual covers Bouncer 0.5.7. Built from source commit cdd3b5958d5be0b33e865b1b56b770f6bccffaf7 (workspace version 0.5.7+34).