Configuration¶
| Env var | Required | Purpose |
|---|---|---|
DATABASE_URL |
yes (server) | PostgreSQL connection string. |
PGPASSWORD |
no | Database password, used when DATABASE_URL carries none. The bundled docker-compose.yml passes it this way so a password containing /, +, @, etc. needs no URL-encoding. |
BLACKBOOK_DATA_DIR |
no | Where the master key / CA / admin bundle live (default /opt/blackbook/data). |
BLACKBOOK_SERVER_SANS |
no | Extra hostnames for the auto-minted server certificate. |
BLACKBOOK_PUBLIC_URL |
no | Server address written into the first-run admin bundle (default https://127.0.0.1:8443). Set it to how clients reach the server, e.g. https://vault.example.com:8443, so bbk login needs no -s. |
BLACKBOOK_MASTER_KEYFILE |
one provider required | Path to a keyfile (kept off the data volume). A random data key is generated once and stored only wrapped under SHA3-256(keyfile). |
BLACKBOOK_MASTER_PASSPHRASE / …_FILE |
one provider required, ≥16 chars | Alternative: a passphrase. The data key is Argon2id(passphrase, salt); only the salt is persisted. Prefer the _FILE form. |
BLACKBOOK_NET_RATE_PER_SEC / BLACKBOOK_NET_BURST |
no | Per-client rate-limit tuning (0 disables). Defaults: 100/s sustained, 200 burst. |
RUST_LOG |
no | Log filter (use info/warn/error in production). |
The master data key is never stored raw. The server requires exactly one provider (keyfile or passphrase) and refuses to start without one. Losing the provider, or the data volume, makes the data unrecoverable — back the provider up separately from the volume.
Database hardening (mutual TLS to PostgreSQL, a least-privilege application role, loaded config) is set up by the scripts in scripts/ and documented in the deployment guide. Copy .env.example to .env and change every password before first boot.
The CLI reads a few variables of its own:
| Env var | Purpose |
|---|---|
BLACKBOOK_PASSPHRASE |
The profile passphrase, for scripts, instead of a prompt or bbk unlock. |
BLACKBOOK_PROFILE / BLACKBOOK_DOMAIN |
Default profile / domain; the same as -P / -D. |
BLACKBOOK_NO_PROMPT |
Fail instead of prompting for a passphrase. |
BLACKBOOK_LOOPBACK_SERVER |
A host[:port] to connect to whenever a profile's server is a loopback address (127.0.0.1, ::1, localhost). It's for running the CLI in a container next to a local server, where loopback means the container itself; scripts/bbk sets it for you. The server is still verified against the profile's pinned CA, so its certificate must cover that host. |