vps/docs/vaultwarden-upstream.md

# Vaultwarden — upstream documentation (source of truth)

Use these when changing `/opt/vaultwarden` on [us2](../hosts/us2.wsvc.info.md). 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](https://github.com/dani-garcia/vaultwarden/wiki/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](../hosts/us2.wsvc.info.md).
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](../runbooks/vaultwarden-health.md) §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](../runbooks/vaultwarden-sqlite-to-postgres.md).