Build a Self-Hosted Secrets Manager with OpenBao on One VPS

OpenBao 2.7.2 on a single VPS: the raft config that actually boots, the secret/ mount that does not exist until you create it, AppRole for your app, dynamic PostgreSQL credentials with working revocation, and measured boot time, memory and snapshot size from repeated runs.

Run OpenBao 2.7.2, the Linux Foundation fork of Vault, as a single-node secrets manager on one VPS: raft storage on a named volume, one KV v2 mount, AppRole so your app never holds a static token, and dynamic PostgreSQL users the database forgets when the lease ends. Every step below was run end to end against a fresh volume; boot to active took 8.0–9.9 s over three boots and idle memory stayed under 41 MiB. Two things cost me real debugging time, and both are in here: a fresh server has no secret/ mount, and the default dynamic role leaves the database user behind on revoke unless you add DROP OWNED BY. Verified 2026-11-17.

What you end up with

One container, one named volume, no external database:

  • KV v2 at secret/, so config values live outside your compose file and your git history.
  • AppRole auth: your app logs in with a role_id and a short-lived secret_id and gets a token with a 20-minute TTL instead of a permanent root token.
  • Dynamic PostgreSQL credentials: the app asks OpenBao for a user, OpenBao creates it in the database with a 5-minute lease, and revoking the lease drops the user.
  • bao operator raft snapshot for backups, one file you can copy off the box.

If all you need is “don’t put passwords in git”, a .env file plus file permissions is cheaper. What this buys you is credentials that expire, an audit trail of who read which path, and a database that never holds a long-lived application password.

The config that boots

# config.hcl
ui = false

storage "raft" {
  path    = "/bao/data"
  node_id = "vps-1"
}

listener "tcp" {
  address     = "0.0.0.0:8200"
  tls_disable = true
}

api_addr     = "http://127.0.0.1:8200"
cluster_addr = "http://127.0.0.1:8201"

Two notes from actually running it. First, do not copy disable_mlock = true from older Vault tutorials: OpenBao 2.7.2 rejects it at startup with unknown or unsupported field. If you want mlock, give the container IPC_LOCK and leave the flag out. Second, keep the listener on plain HTTP inside the container and terminate TLS in front of it (Caddy, nginx, or a Cloudflare tunnel); a self-signed cert here only moves the problem.

# compose.yaml
services:
  bao:
    image: openbao/openbao:2.7.2
    container_name: bao
    restart: unless-stopped
    ports:
      - "127.0.0.1:8200:8200"
    volumes:
      - ./config.hcl:/bao/config.hcl:ro
      - bao-data:/bao/data
    command: server -config=/bao/config.hcl

volumes:
  bao-data:

The image runs as uid 100, but Docker creates a fresh named volume as root. Without fixing ownership the container exits immediately with a permission error on /bao/data:

docker volume create bao-data
docker run --name bao-chown --user 0 -v bao-data:/bao/data \
  --entrypoint /bin/chown openbao/openbao:2.7.2 -R 100:100 /bao/data
docker rm -f bao-chown
docker compose up -d

With the volume already owned correctly, the listener answered on /v1/sys/health 0.53 s after docker run, the one place I timed it to the millisecond.

Initialise, unseal, and keep the keys

docker exec bao bao operator init -key-shares=1 -key-threshold=1
docker exec bao bao operator unseal <unseal-key>
export BAO_ADDR=http://127.0.0.1:8200
docker exec -e BAO_ADDR=$BAO_ADDR bao bao status

init prints the unseal key and the initial root token exactly once. Store the unseal key somewhere that is not the VPS. A password manager entry is fine. This test used 1 share / 1 threshold; for anything real use 5/3 so losing one key does not lose the store and one stolen key does not open it.

There is no auto-unseal here: the container starts sealed on every boot. Health returns 503 until you unseal, and bao status says Sealed true. The alternative is a cloud KMS, which reintroduces the dependency you were avoiding. Plan the unseal into your restart runbook, not as an afterthought at 3 a.m.

The secret/ mount that is not there

Vault’s dev server mounts secret/ for you. A production OpenBao 2.7.2 server does not: bao secrets list returns cubbyhole/, identity/ and sys/ and nothing else, and the first bao kv put secret/... fails with a 404 on a path that looks like it should exist.

docker exec -e BAO_ADDR=$BAO_ADDR bao bao secrets enable -path=secret kv-v2
docker exec -e BAO_ADDR=$BAO_ADDR bao bao kv put secret/app/db password='change-me'
docker exec -e BAO_ADDR=$BAO_ADDR bao bao kv get secret/app/db

AppRole: a token your app can earn

Create a policy that can read one path and nothing else:

# app-reader.hcl
path "secret/data/app/*" {
  capabilities = ["read"]
}

path "database/creds/app" {
  capabilities = ["read"]
}
docker exec -e BAO_ADDR=$BAO_ADDR bao bao policy write app-reader /bao/app-reader.hcl
docker exec -e BAO_ADDR=$BAO_ADDR bao bao auth enable approle
docker exec -e BAO_ADDR=$BAO_ADDR bao bao write auth/approle/role/app \
  token_policies=app-reader token_ttl=20m token_max_ttl=1h

Then hand the app a role_id (not secret, it identifies the role) and a secret_id (secret, rotate it per environment). The app logs in at boot:

curl -s -X POST "$BAO_ADDR/v1/auth/approle/login" \
  -d '{"role_id":"...","secret_id":"..."}' | jq -r .auth.client_token

Measured from the host: an AppRole login round trip took 0.18 s and 0.22 s in two runs. With that token, reads of secret/data/app/db succeed; a read of any other path, a LIST, and a write all returned 403, so a leaked app token cannot touch sys/ or another app’s secrets.

Dynamic PostgreSQL credentials

This is the feature that justifies the whole container. Enable the database engine and point it at your Postgres:

docker exec -e BAO_ADDR=$BAO_ADDR bao bao secrets enable database
docker exec -e BAO_ADDR=$BAO_ADDR bao bao write database/config/pg \
  plugin_name=postgresql-database-plugin \
  allowed_roles=app \
  connection_url="postgresql://{{username}}:{{password}}@pg:5432/app?sslmode=disable" \
  username=postgres password="$BOOTSTRAP_PW"

The role definition is where the trap is. Put it in a file so the quoting stays readable:

{
  "db_name": "pg",
  "default_ttl": "5m",
  "max_ttl": "1h",
  "creation_statements": [
    "CREATE ROLE \"{{name}}\" WITH LOGIN PASSWORD '{{password}}' VALID UNTIL '{{expiration}}';",
    "GRANT USAGE ON SCHEMA public TO \"{{name}}\";"
  ],
  "revocation_statements": [
    "DROP OWNED BY \"{{name}}\";",
    "DROP ROLE IF EXISTS \"{{name}}\";"
  ]
}
docker exec -i bao bao write database/roles/app @/tmp/role.json
docker exec -e BAO_ADDR=$BAO_ADDR bao bao read database/creds/app

Two measured runs, fresh volume and fresh Postgres each time: issuing a credential set took 0.17 s and 0.19 s, the lease came back as 300 s, the username was 42 characters (v-root-app-…), and the created user was not a superuser (select usesuper → false) while has_schema_privilege(current_user,'public','usage') → true.

The revoke that silently fails

My first role definition had only creation_statements. bao lease revoke returned “All revocation operations queued successfully!” and the user stayed in the database with a working password. The OpenBao log said why:

expiration: failed to revoke lease: ... err: ERROR: role "v-root-app-…"
cannot be dropped because some objects depend on it (SQLSTATE 2BP01)
attempts=1 next_attempt=20.293641015s

The GRANT USAGE ON SCHEMA public creates a dependency, and DROP ROLE refuses while it exists. The lease is retried in the background, so the failure is quiet unless you read the log. The fix is the revocation_statements block above: DROP OWNED BY first, then DROP ROLE. With that in place, bao lease revoke -sync <lease> returned “Success! Revoked lease” and, one second later, pg_roles had zero rows for that user and a psql login with the revoked password failed with “role … does not exist”.

Rotating the root password

docker exec -e BAO_ADDR=$BAO_ADDR bao bao write -f database/rotate-root/pg

After this, the bootstrap password in your compose file no longer works. That is also why you should not keep it in a file you plan to re-apply later. Dynamic credentials issued after the rotation still connected fine.

Verify it from another container, not from inside the Postgres container. The official postgres image’s pg_hba.conf trusts 127.0.0.1, so a psql run inside that container authenticates no matter what password you pass: my wrong-password control test also “succeeded”. Connecting from a second container on the same Docker network is what actually proves password auth:

docker run --name pgclient --network appnet -e PGPASSWORD=bootstrap-pw \
  postgres:17-alpine psql -h pg -U postgres -d app -tAc 'select current_user'

That failed with an authentication error after the rotation, and a freshly issued dynamic user connected successfully in the same command.

Backups

docker exec -e BAO_ADDR=$BAO_ADDR bao bao operator raft snapshot save /bao/backup.snap
docker cp bao:/bao/backup.snap ./bao-$(date +%F).snap

On a store with one KV secret, one database config and one role, the snapshot was 25,113 bytes in both runs. Restore with bao operator raft snapshot restore -force, then unseal. The snapshot is only half a backup: without the unseal key it is a brick, so back the key up separately.

What it costs on one VPS

Measured with docker stats --no-stream after init and unseal, and date +%s.%N around each step:

Metric Run 1 Run 2 Run 3
Init + unseal → active (200) 9.67 s 8.04 s 9.87 s
Idle memory 40.3 MiB 24.2 MiB 22.8 MiB
Raft snapshot 25,113 B 25,113 B —
AppRole login 0.217 s 0.180 s —
Dynamic credential issued 0.193 s 0.171 s —
Listener reachable — — 0.53 s

A dash means I did not time that metric in that run; nothing here is extrapolated. CPU stayed below 1% in every sample.

The spread in memory is page cache and election timing right after unseal, not a leak: a single-node raft installation with an idle API sits in the low tens of megabytes. For comparison, the Postgres 17 instance used as the test target idled at 24.0 MiB and was ready in 3 s.

Common problems

  • Container exits immediately after up -d. The named volume is root-owned and the image runs as uid 100. Run the chown helper container once before starting the service.
  • unknown or unsupported field: disable_mlock. OpenBao 2.7.2 does not accept it. Remove the line; add cap_add: [IPC_LOCK] if you want the memory locked.
  • 404 on kv put secret/.... There is no default secret/ mount outside dev mode. bao secrets enable -path=secret kv-v2.
  • Health returns 503 after a reboot. The server is sealed. Unseal with your key; there is no auto-unseal without a KMS.
  • Revoked database users stay alive. Missing revocation_statements with DROP OWNED BY. Check docker logs bao for SQLSTATE 2BP01.
  • Password rotation looks like a no-op. You tested from inside the Postgres container, where 127.0.0.1 is trusted. Test from a second container.
  • App gets 403 on a path it can read. The policy path for KV v2 is secret/data/..., not secret/...; the extra data segment is the versioned layout.

Related guides