Skip to content

Deployment and Proxy

Jump to bottom
KelTech Services edited this page Jul 13, 2026 · 1 revision

Deployment & proxy

Install: compose up, done

Deploy the example compose stack and start it - that's the whole install. No folders to pre-create, no files to seed. On first boot IdPVault generates its master encryption key inside the secrets volume, fixes volume ownership itself, then drops to a non-root user (uid 10001) to run. Named volumes are the default; prefer host bind mounts? Swap the volume names for host paths in the stack - nothing else changes.

Architecture

Two containers: the IdPVault app (runs as a non-root user) and a Postgres database. Persistent data lives in three volumes: /data (encrypted snapshots), /secrets (the master encryption key), and the Postgres volume. The database is only reachable inside the stack's private network; setting a unique POSTGRES_PASSWORD in the stack environment is recommended.

The master key

The master key is the root of all envelope encryption: tenant credentials, snapshots, and the SMTP password are all encrypted under keys wrapped by it. Back it up right after first boot: docker cp idpvault:/secrets/master.key ./master.key.backup - store it somewhere safe and separate from the host. If the key is lost, existing snapshots are unrecoverable by design (there is no escrow and no phone-home). IdPVault protects you from the two dangerous states: if the key file is missing but data exists, the container refuses to start rather than generate a fresh key; if a wrong key is mounted against an existing database, the app refuses to boot.

Reverse proxy & HTTPS

  • Put IdPVault behind your reverse proxy with a real hostname and TLS.

  • Set Settings → Core → Public URL to that address; email links use it, and cookies switch to Secure via the proxy's X-Forwarded-Proto header (make sure your proxy sends it).

  • Once confirmed working, optionally enable Enforce host to reject requests addressed to any other hostname (/healthz and /metrics stay exempt).

Scheduling & performance

Backups queue and run one at a time by default, so same-time schedules never overload a modest host; each job starts the moment the previous one finishes, and same-tenant runs never overlap. Hosts with headroom can opt into parallel runs by setting the IDPVAULT_BACKUP_WORKERS environment variable (default 1) in the stack. Schedules are evaluated in the org timezone (Settings → Core, DST-aware); snapshot names and storage remain UTC.

Health & monitoring

/healthz is the only unauthenticated endpoint (returns status + version). A token-guarded Prometheus /metrics endpoint is available for scraping. A daily self-check alerts if any scheduled tenant has gone too long without a successful backup.

Updates

Upgrades are image pulls; the schema migrates additively on boot. Take a backup of the IdPVault volumes before major upgrades, as with any stateful service.

Clone this wiki locally