Skip to content

Vaultwarden

Lifecycle: Current. Container/unit verified: 2026-07-17.

Service record

Field Value
Purpose Organizational password vault
Owner IT Operations
Criticality / recovery priority Critical / P3 after database
Host/runtime CT 101, rootless Podman as podsvc
Image ghcr.io/dani-garcia/vaultwarden:latest-alpine
Unit vaultwarden.service
Route/backend pass.kh3group.com / 192.168.2.20:30081
Data /opt/podman/volumes/vaultwarden/data
Env /opt/podman/env/vaultwarden.env, mode 0600
Database PostgreSQL vaultwarden

Dependencies and sensitive state

Vaultwarden depends on PostgreSQL, Caddy, DNS, and optional SMTP/OIDC. Back up the PostgreSQL database and /data together; /data contains cryptographic keys and attachments. Secret names include database password, admin token, SMTP credential, and optional OIDC secret.

Operate and validate

ssh pvessh 'pct exec 101 -- runuser -l podsvc -c \
  "XDG_RUNTIME_DIR=/run/user/2000 systemctl --user status vaultwarden.service --no-pager"'
ssh pvessh 'pct exec 101 -- runuser -l podsvc -c \
  "podman logs --tail=200 vaultwarden"'
ssh pvessh 'curl -sS -o /dev/null -w "%{http_code}\n" \
  http://192.168.2.20:30081/'

Expected: active unit and a normal HTTP response. Complete validation requires an approved user to log in, unlock a vault, and check an attachment/send.

Upgrade

  1. Read Vaultwarden release notes and database requirements.
  2. Back up database, /data, env, and Quadlet from the same recovery point.
  3. Pin/test the new image in an isolated target.
  4. Pull and restart only this unit in an approved window.
  5. Validate login, unlock, attachments, admin access, SMTP, and OIDC as configured.
  6. Restore image plus matching data/database if rollback is supported.

Restore

Restore /data with rootless ownership, restore the PostgreSQL database/role, install the secret env file, start PostgreSQL, then Vaultwarden. If recovered SMTP contains SMTP_HOST without SMTP_FROM, keep SMTP disabled until a complete configuration is approved; do not append duplicate empty variables.

Security and monitoring

  • Keep sign-ups disabled unless approved.
  • Protect admin access and rotate exposed tokens.
  • Never regenerate encryption/key material silently during restore.
  • Monitor backend/HTTPS, database, disk, backup age, login errors, and email tests where configured.

Troubleshooting

Symptom Diagnosis Remedy
Login/unlock failure Time, logs, database, OIDC Repair failed dependency; do not reset user data
Attachment missing /data restore/ownership Restore matching data snapshot and ownership
Email failure Complete SMTP keys and network Correct restricted env; validate without logging credentials
502 Backend 30081, unit, PostgreSQL Repair backend before Caddy

Official references