54 lines
3.7 KiB
Markdown
54 lines
3.7 KiB
Markdown
# 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.
|
|
|
|
Replay migration steps: [runbooks/vaultwarden-sqlite-to-postgres.md](../runbooks/vaultwarden-sqlite-to-postgres.md).
|