Vaultwarden

Overview

Vaultwarden is a compact Rust implementation of the Bitwarden server API for individuals, families, and small teams. It supports the official Bitwarden web vault, mobile apps, desktop clients, and browser extensions, as well as attachments, organizations, Send, and two-step login.

This recipe uses embedded SQLite and keeps the database, attachments, keys, and configuration in a single local Docker volume. That is the whole appeal — and the reason it does not claim the reliable level, which asks for a separate database, monitoring, and resource limits.

Vaultwarden is not associated with Bitwarden, Inc. Report server and compatibility issues to the Vaultwarden project, not official Bitwarden support.

Security assessment

The container runs without privileged, host networking, or a Docker socket, uses no-new-privileges, and binds its port only to 127.0.0.1. Registration and invitations are disabled by default. /admin is unavailable because the recipe does not set ADMIN_TOKEN.

Treat this container as the most valuable thing on the server. Serve it over HTTPS only, turn on two-factor authentication for every account, apply image updates quickly, and encrypt any copy that leaves the machine — a backup archive here is the vault.

If you do need /admin, follow the upstream guide: generate an Argon2id hash of the token, keep it out of Git, and restrict the path at the reverse proxy or behind a VPN.

Step-by-step guide

1. Check the server

Budget at least 1 CPU, 256 MB of RAM, and 1 GB of local disk; 512 MB of RAM plus room for attachments and backups is more comfortable. Upstream publishes no formal minimum, so these are our conservative figures for this recipe. You need Ubuntu 22.04+ or Debian 12+ with Docker Engine and Docker Compose v2.24+.

docker --version
docker compose version

2. Prepare files and variables

Put the recipe files in a dedicated directory and create a private .env:

mkdir -p ~/services/vaultwarden
cd ~/services/vaultwarden
cp .env.example .env
chmod 600 .env

Set VAULTWARDEN_DOMAIN to the real external URL without a trailing slash. VAULTWARDEN_VERSION pins the image; VAULTWARDEN_PORT selects the local port; VAULTWARDEN_DATA_VOLUME names the volume; VAULTWARDEN_SIGNUPS_ALLOWED and VAULTWARDEN_INVITATIONS_ALLOWED control user enrollment; TZ sets the time zone. All persistent data lives under /data in the volume.

3. Create the first account

Sign-ups are closed by default, so the first account needs a brief exception. Keep the port on localhost throughout, set VAULTWARDEN_SIGNUPS_ALLOWED=true in .env, and start the container:

docker compose pull
docker compose up -d
docker compose ps
ssh -L 8000:127.0.0.1:8000 user@server.example

Open http://localhost:8000, register the account, then set VAULTWARDEN_SIGNUPS_ALLOWED=false again and apply it with docker compose up -d. Do this before the service is reachable from anywhere else — an open Vaultwarden takes registrations from whoever finds it.

Working over localhost is fine here because browsers treat it as a secure context; every remote path to the web vault needs real HTTPS.

VPS deployment

Keep the 127.0.0.1 bind on a VPS, block port 8000 externally, and publish the service only through an HTTPS reverse proxy. Check the built-in healthcheck:

docker compose up -d
docker compose ps
curl --fail http://127.0.0.1:8000/alive

Trusted LAN access

Without TLS, use an SSH tunnel or VPN. If the reverse proxy runs on another trusted LAN host, replace 127.0.0.1 in compose.yaml with the server’s specific LAN address, restrict the port to the proxy address at the firewall, and still use HTTPS. Do not expose the backend on 0.0.0.0 without network restrictions.

Domain and HTTPS

Replace vault.example.com in .env and the chosen proxy/ file with the same domain. proxy/Caddyfile obtains a certificate automatically; proxy/nginx.conf expects a Certbot certificate; proxy/traefik.yaml uses the letsencrypt resolver. All examples proxy WebSockets over the main port. If Traefik runs in a container, replace 127.0.0.1 with a reachable host-gateway address.

Check the public endpoint with curl --fail https://vault.example.com/alive. The web vault and the mobile clients both insist on a complete, valid certificate chain — a partial chain fails on Android while a browser still accepts it.

Backup

chmod +x backup.sh restore.sh
./backup.sh

The script stops Vaultwarden, archives the complete /data volume, and starts the container again. This captures SQLite and its WAL consistently. The archive contains the database, attachments, Sends, RSA keys, and possible secrets from config.json: encrypt it and keep at least one copy off-server. Upstream recommends regular, at least daily backups and periodic restore tests.

Restore

Restore completely replaces the volume contents with the selected archive:

./restore.sh ./backups/vaultwarden-YYYYMMDDTHHMMSSZ.tar.gz
docker compose ps
curl --fail http://127.0.0.1:8000/alive

The script creates a safety backup of current data before replacement. Do not mix files from different snapshots: db.sqlite3 and db.sqlite3-wal, when present, must come from the same stopped instance.

Update

Create a backup, read the release notes, and check client compatibility. Change only the pinned VAULTWARDEN_VERSION, then run:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs --tail=100 vaultwarden

Rollback

Do not run an old image over a database migrated by a newer release. Restore the previous VAULTWARDEN_VERSION in .env, stop the service, and restore the archive created before updating:

docker compose pull
docker compose stop vaultwarden
./restore.sh ./backups/vaultwarden-before-update.tar.gz
docker compose up -d

Review the release notes: some data-format changes can prevent a downgrade without restoring the complete, consistent /data backup.

Stop and remove

docker compose down removes the container but preserves the volume. To remove everything irreversibly after checking the backup:

docker compose down
docker volume rm vaultwarden-data
rm -rf ~/services/vaultwarden

Sources: official installation, configuration, HTTPS, backup, and admin page.

Troubleshooting

Container does not become healthy

docker compose ps
docker compose logs --tail=200 vaultwarden
docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q vaultwarden)"

Check free disk space and volume write access. The /alive endpoint verifies both HTTP service and a database connection.

Web vault reports an insecure context

The remote web vault requires HTTPS for Web Crypto APIs. Confirm that VAULTWARDEN_DOMAIN starts with https://, the certificate serves the full chain, and the proxy forwards Host and X-Forwarded-Proto. Plain HTTP is acceptable only through local localhost during initial setup.

Clients do not synchronize immediately

WebSockets use the main port and /notifications/hub. Check the Upgrade and Connection headers in Nginx. Caddy and Traefik handle protocol upgrades automatically. Mobile push notifications require separate upstream setup and are outside this recipe’s test scope.

A user cannot register

This is the secure default. Temporarily set VAULTWARDEN_SIGNUPS_ALLOWED=true, run docker compose up -d, create the required account over a protected connection, and immediately restore false.

Changes in .env have no effect

If settings were previously saved through /admin, /data/config.json overrides matching environment variables. Inspect diagnostics and the file, but do not publish it: it may contain tokens and SMTP passwords.

The installation looks empty after an update

Confirm that the original volume is attached and do not create a new user:

docker compose config
docker volume inspect vaultwarden-data
docker compose exec vaultwarden ls -la /data

If the wrong volume is selected, stop the container and correct VAULTWARDEN_DATA_VOLUME. Do not remove the old volume before checking a backup.