Vaultwarden

Vaultwarden is a self-hosted password manager compatible with Bitwarden clients — browser extensions, mobile apps, and the desktop client. It can hold access credentials to everything else you run; treat setup and backup accordingly.

Written against 1.37.0 · no verification recorded against that version

Not exercised: a restore. The database, the RSA signing keys and the attachments have to come back from the same point in time, and that has not been performed here.

Needs: Traefik running, a domain, and SMTP credentials (email verification is on by default).

Installation

From apps/vaultwarden/:

1. cp .env.example .env

2. Set your domain in .env:

   APP_TRAEFIK_HOST=vault.example.com

3. Set SMTP — required before the first account can verify its email:

   VW_SMTP_HOST=smtp.example.com
   VW_SMTP_FROM=vault@example.com
   VW_SMTP_PORT=587
   VW_SMTP_SECURITY=starttls
   VW_SMTP_USERNAME=your-smtp-user
   VW_SMTP_PASSWORD=your-smtp-password

4. Generate database passwords. Hex is a convention here, not a requirement: the password ends up inside a connection URL, and hex avoids having to URL-encode characters that would otherwise break it.

   sed -i "s|^DB_PASSWORD=.*|DB_PASSWORD=$(openssl rand -hex 32)|" .env
   sed -i "s|^DB_ROOT_PASSWORD=.*|DB_ROOT_PASSWORD=$(openssl rand -hex 32)|" .env

5. Generate the admin token. Vaultwarden accepts a plain-text token as well; this setup deliberately does not, because a plain token in .env is readable by anything that can read the file or inspect the container:

   docker compose run --rm --no-deps app /vaultwarden hash

   Note

   Use docker compose run, not docker run. A plain docker run does not read this directory’s .env, so ${APP_TAG} would expand to nothing and the image reference would be invalid. Compose resolves it from the service definition.

   Copy the full $argon2id$... output, then paste it into .env with every $ doubled (Compose escaping):

   VW_ADMIN_TOKEN=$$argon2id$$v=19$$m=65540,t=3,p=4$$...your-hash...

   Caution

   This stack is a documented exception to the file-based credential handling. The admin token and the database password reach the container as environment variables rather than as mounted secret files — the database credential is embedded in a connection URL, which a _FILE variable cannot express without an entrypoint assembling it. The practical consequence: both values are visible in docker inspect and in docker compose config output. Treat .env accordingly, and redact before pasting that output anywhere.

6. Allow signups for your first account — you’ll turn this off again right after:

   VW_SIGNUPS_ALLOWED=true

7. Start:

   docker compose up -d
   docker compose logs -f

   Wait for Starting Vaultwarden with no errors — MariaDB has a health check Vaultwarden waits on.

Verify

docker compose ps                      # both containers healthy
curl -sI https://your-domain/alive     # expect 200 OK

Open https://your-domain — the login page should load over TLS.

Create your account and lock signups

1. Click Create Account, register, and verify your email.

2. In .env, turn signups back off:

   VW_SIGNUPS_ALLOWED=false

   docker compose up -d --force-recreate app

   Caution

   docker compose restart will not do this. Restarting stops and starts the existing container, which keeps the environment it was created with — the vault would keep accepting signups while the login page suggests otherwise. Recreating is what applies a changed .env.

   Confirm it took effect against the container rather than against the page:

   docker compose exec app env | grep SIGNUPS_ALLOWED   # expect false

   Then reload the login page — “Create Account” should be gone.

3. At https://your-domain/admin, set:

   Setting	Value
   Allow new signups	false
   Allow password hints	false
   Block non-global IPs	true
   Disable 2FA remember	true

4. Enable 2FA on your account: Settings → Security → Two-step login.

Going further

Public access instead of Tailscale-only

The installation above uses the default, APP_TRAEFIK_ACCESS=acc-tailscale — the vault is reachable only over Tailscale/VPN. Setting APP_TRAEFIK_ACCESS=acc-public makes it reachable from the open internet instead. That’s a deliberate change to your attack surface, not a default — decide it before exposing real credentials.

Backup before real use

Do not add real credentials before a backup exists.

What to back up: volumes/mysql/ (database), volumes/data/attachments/, volumes/data/rsa_key.* (signing keys — without these, sessions break on restore even with an intact database), volumes/data/sends/.

docker exec -e MYSQL_PWD="$(grep DB_ROOT_PASSWORD .env | cut -d= -f2)" \
  vaultwarden-db mariadb-dump -u root vaultwarden > backup-$(date +%Y%m%d).sql

The command above is a one-off dump. To have it run on a schedule alongside the data directories, and to hold the archives somewhere the server cannot reach, see backup and restore — Borgmatic on the host, with the database dump wired in as a pre-backup hook.

Caution

The three parts have to be restored together, from the same point in time. The database alone is not enough: without rsa_key.* every session breaks even though the vault contents are intact, and without the attachments directory entries lose their files. A restore of this stack has not been performed — the procedure is written down, and that is not the same thing.

Updates

1. Check the release notes for breaking changes.
2. Back up all three parts together — the database dump, volumes/data/rsa_key.* and volumes/data/attachments/. A database-only snapshot is not something you can roll back to: restoring it without the matching signing keys breaks every session even though the vault contents are intact.
3. Update APP_TAG in .env.

4. docker compose pull
   docker compose up -d

5. Verify /alive and log in.

Troubleshooting

Caution

Container not starting — check docker compose logs app and docker compose logs db. Common causes: MariaDB not yet healthy (the app waits for it), or incorrect $$ escaping in VW_ADMIN_TOKEN.

Note

Login page not loading but the container is healthy — check Traefik logs and confirm APP_TRAEFIK_HOST matches your DNS record exactly.

Email verification not arriving: send a test email from /admin → Settings, and check your SMTP provider’s outbound log if it fails.

Repository files

• apps/vaultwarden/README.md — full setup and admin panel settings
• apps/vaultwarden/.env.example
• apps/vaultwarden/UPSTREAM.md — upstream notes, backup, and upgrade steps