This tutorial was written with AI assistance from the project's official documentation. Verification status is stated at the end of the article.
What Vaultwarden does and what it needs
Vaultwarden is a Rust reimplementation of the Bitwarden client API. It speaks the same protocol as the official Bitwarden clients (browser extensions, mobile, desktop, CLI), so you point them at your own server instead of bitwarden.com. The upstream project targets self-hosters who don't want to run the resource-heavy official stack.
Feature coverage is broad: personal vault, Send, attachments, website icons, organizations with collections and groups, event logs, admin password reset, TOTP/email/FIDO2/YubiKey/Duo 2FA, emergency access, and the Vaultwarden admin backend. The web vault is bundled inside the container image.
The upstream project does not publish a minimum memory figure. In practice, idle memory is modest because the binary is Rust and the default database is SQLite. Memory grows with concurrent client syncs, attachment uploads, and icon-cache fetches. If you enable a MySQL or PostgreSQL backend, budget for that database process too.
One hard requirement from the README: the web vault needs a secure context for the Web Crypto API. That means HTTPS. Plain HTTP on a public IP will not work for the browser vault.
Prerequisites, ports, and volume constraints
- A Linux host with Docker Engine 24+ and the Compose plugin (
docker compose version). - A DNS record pointing at the host, e.g.
vw.example.com. You need this before the reverse proxy step. - Port 80 and 443 free for the reverse proxy. Vaultwarden itself listens on container port 80 (the image maps
ROCKET_PORT=8000internally but the container exposes 80). - A persistent volume for
/data. This holdsdb.sqlite3,rsa_key,attachments/,sends/,icon_cache/, andtmp/. Lose it and you lose every vault. - Outbound HTTPS if you keep
ICON_SERVICE=internal(default) so the server can fetch site icons. SetDISABLE_ICON_DOWNLOAD=trueif you want to block that.
The official README example publishes 127.0.0.1:8000:80. We keep that binding so the app is reachable only from the host and the reverse proxy terminates TLS.
Production Docker Compose setup
Create the project directory and the data volume, then write the compose file and .env.
mkdir -p /opt/vaultwarden && cd /opt/vaultwarden
mkdir -p vw-data
Generate secrets. ADMIN_TOKEN protects the /admin panel; treat it like a root password. The PUSH_INSTALLATION_KEY is only needed if you enable mobile push, but generating it now avoids a later restart.
openssl rand -hex 32 # ADMIN_TOKEN
openssl rand -hex 32 # PUSH_INSTALLATION_KEY (optional)
Write .env (replace the placeholders with the values you just generated, and set DOMAIN to your real HTTPS URL):
cat <<'EOF' > .env
DOMAIN=https://vw.example.com
ADMIN_TOKEN=REPLACE_WITH_OPENSSL_HEX
PUSH_INSTALLATION_KEY=REPLACE_WITH_OPENSSL_HEX
SIGNUPS_ALLOWED=true
TZ=UTC
LOG_LEVEL=info
EOF
chmod 600 .env
Write compose.yml:
cat <<'EOF' > compose.yml
services:
vaultwarden:
image: vaultwarden/server:latest
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: ${DOMAIN}
ADMIN_TOKEN: ${ADMIN_TOKEN}
PUSH_INSTALLATION_KEY: ${PUSH_INSTALLATION_KEY}
SIGNUPS_ALLOWED: ${SIGNUPS_ALLOWED:-true}
TZ: ${TZ:-UTC}
LOG_LEVEL: ${LOG_LEVEL:-info}
ENABLE_WEBSOCKET: "true"
IP_HEADER: X-Real-IP
IP_HEADER_TRUSTED_PROXIES: local
volumes:
- ./vw-data:/data
ports:
- 127.0.0.1:8000:80
EOF
Start it:
docker compose up -d
docker compose logs -f vaultwarden
You should see Rocket bind and a line about the database. The app is now listening on 127.0.0.1:8000 only. To test without a domain, either SSH-tunnel (ssh -L 8000:127.0.0.1:8000 user@host) and open http://localhost:8000, or temporarily change the port mapping to 8000:80 and accept that the web vault will refuse to run over plain HTTP.
Reverse proxy, HTTPS, and first-run hardening
Vaultwarden's README is explicit: use a reverse proxy and enable HTTPS. The web vault will not function without a secure context. The proxy must also forward WebSocket upgrades because ENABLE_WEBSOCKET=true is set above; the Bitwarden clients use the WebSocket for live sync notifications.
Caddy example (/etc/caddy/Caddyfile):
vw.example.com {
encode zstd gzip
reverse_proxy 127.0.0.1:8000
}
Caddy handles WebSocket upgrades automatically and provisions a Let's Encrypt certificate once DNS resolves. If you use Nginx instead, you need explicit upgrade headers:
location / {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
client_max_body_size 525M;
}
The client_max_body_size matters: attachments and Sends are uploaded through the proxy, and the default 1 MB Nginx limit will break them. Caddy has no such limit by default.
DOMAIN in .env must match the public URL exactly, including scheme and any subpath. The Bitwarden clients read it from the server config and use it for WebSocket and API calls. A mismatch causes sync failures that look like network errors.
First-run hardening, in order:
- Open
https://vw.example.comand register your account. The first account is the one you'll use. - Immediately set
SIGNUPS_ALLOWED=falsein.envand rundocker compose up -dto recreate the container. Otherwise anyone who finds the host can create an account. - Log in to
https://vw.example.com/adminwith theADMIN_TOKENand confirm the panel loads. If it doesn't, the token in.envdoesn't match what the container read; checkdocker compose config. - Enable 2FA on your account from the web vault settings. Vaultwarden supports TOTP, email, FIDO2, YubiKey, and Duo.
- If you plan to invite others, configure SMTP (
SMTP_HOST,SMTP_FROM,SMTP_SECURITY,SMTP_PORT,SMTP_USERNAME,SMTP_PASSWORD) so invitation and verification emails actually send. Without SMTP, invitations silently fail.
Updating, backups, and common pitfalls
Update:
cd /opt/vaultwarden
docker compose pull
docker compose up -d
docker compose logs --tail=50 vaultwarden
Vaultwarden migrations run on startup. Read the release notes before jumping major versions; the project occasionally changes defaults.
Backup. The only state that matters is the vw-data directory (mounted at /data). Stop the container for a consistent SQLite snapshot, or use SQLite's online backup if you can't afford downtime:
cd /opt/vaultwarden
docker compose stop vaultwarden
tar czf vaultwarden-$(date +%F).tar.gz vw-data
docker compose start vaultwarden
Store that tarball off-host. It contains db.sqlite3, rsa_key (used to sign auth tokens), attachments, and Sends. Restoring is the reverse: stop, replace vw-data, start.
Two pitfalls worth knowing:
- The web vault needs HTTPS, full stop. The README calls this out because the Web Crypto API requires a secure context. If you test over plain HTTP, the vault UI will load but crypto operations fail. Don't debug the app; fix the TLS termination.
-
DOMAINmust be the public URL, not the internal one. SettingDOMAIN=http://localhostorDOMAIN=http://127.0.0.1:8000while serving over HTTPS breaks client sync and WebSocket connections. The value is handed to clients as the server base URL.
If you enable mobile push later, set PUSH_ENABLED=true and keep PUSH_INSTALLATION_ID and PUSH_INSTALLATION_KEY stable across restarts; regenerating them invalidates registrations. For most self-hosters, leaving push off is fine and avoids sending metadata to Bitwarden's relay.
Measured in our sandbox run: total memory 7.1 MB (sum of per-container peaks over a 30s idle window after startup) across 1 container; largest container 7.1 MB; published port(s) 8000; HTTP probe returned 200. The run took 99.3s with the image already cached; a fresh server also has to download it. Required secret(s) ADMIN_TOKEN, DOMAIN, PUSH_INSTALLATION_KEY were generated for the test run, as the tutorial instructs.
Verification: we ran this docker-compose stack in a disposable Docker environment and recorded the measurements above. They describe that run, not a guarantee for your host.
Originally published with full interactive benchmark metrics and server sizing notes at https://benchrun.pages.dev/vaultwarden-docker-compose-self-hosting/.
Top comments (0)