vps/docs/vaultwarden-upstream.md

Vaultwarden — upstream documentation (source of truth)

Use these when changing /opt/vaultwarden on us2. Prefer upstream over blog posts or Obsidian notes.

Primary references

Topic	URL
Configuration overview (methods + precedence)	https://github.com/dani-garcia/vaultwarden/wiki/Configuration-overview
Env / options template (canonical variable list)	https://github.com/dani-garcia/vaultwarden/blob/main/.env.template
Defaults / implementation source	https://github.com/dani-garcia/vaultwarden/blob/main/src/config.rs
PostgreSQL backend + SQLite migration	https://github.com/dani-garcia/vaultwarden/wiki/Using-the-PostgreSQL-Backend
SMTP	https://github.com/dani-garcia/vaultwarden/wiki/SMTP-configuration
Reverse proxy examples (incl. Traefik)	https://github.com/dani-garcia/vaultwarden/wiki/Proxy-examples
Enabling admin page / ADMIN_TOKEN	https://github.com/dani-garcia/vaultwarden/wiki/Enabling-admin-page
Disable registration / invitations	https://github.com/dani-garcia/vaultwarden/wiki/Disable-registration-of-new-users
pgloader BIGINT login failure note	https://github.com/dani-garcia/vaultwarden/discussions/7134
Project wiki home	https://github.com/dani-garcia/vaultwarden/wiki
Container image	https://github.com/dani-garcia/vaultwarden/pkgs/container/server

Configuration precedence (official)

From Configuration overview:

1. Compile-time defaults (src/config.rs)
2. Vaultwarden ENV_FILE / .env read by the process (if used)
3. Process environment variables (e.g. Docker Compose env_file + environment) — override (2)
4. data/config.json from /admin — highest precedence (overrides env)

Official stance: prefer environment variables; config.json is not the recommended long-term method. Once admin saves config.json, those keys stop being changeable via .env until removed/edited in admin or the file.

Settings we care about on us2

Concern	Upstream guidance	Our notes (post-2026-08-01 migrate)
Public URL	Set DOMAIN e.g. https://auth.wsvc.info (no trailing slash)	Set in compose + config.json
SMTP	587+starttls or 465+force_tls	Effective: 587/starttls to mx2 (465 unreachable from us2); extra_hosts pins A 194.163.160.244
SMTP password	Same mailbox password as mailcow	Must match across .env, config.json, .smtp-credentials. Admin/config.json wins — stale admin password → SMTP 535 while .env still works
Database	DATABASE_URL for Postgres	Live: Postgres via compose DATABASE_URL; sqlite cold under backups/sqlite-cold/
Client IP behind proxy	Traefik → prefer X-Forwarded-For	ip_header=X-Forwarded-For in config.json
Admin	Argon2 ADMIN_TOKEN	On server only
Signups	Invite-only on public URL	signups_allowed=false

Agent checklist before edits

1. Read this page + us2 host facts.
2. On the server, compare .env, compose environment, and /data/config.json (including SMTP password fingerprint, not plaintext in chat/logs).
3. Change the layer that actually wins (often config.json); if rotating the mailbox password, update all three secret stores.
4. After recreating the vaultwarden container, restart Traefik if auth.wsvc.info 404s.
5. Do not commit secrets; do not copy passwords from Obsidian into this repo.
6. Verify SMTP with AUTH (not TCP-only) — vaultwarden-health §5.

Operations path

Use ansible/playbooks/health-report.yml --limit vaultwarden for routine status. After a reviewed effective-configuration change that needs a container recreate, use the allowlisted compose-reconcile.yml target vaultwarden. Add service_reconcile_restart_traefik=true only when the documented post-recreate 404 occurs. Direct Compose commands remain diagnostic tools, not the routine control path.

Replay migration steps: runbooks/vaultwarden-sqlite-to-postgres.md.