// Engineering Log
Secrets and Zero Trust: Part 2 — Vaultwarden behind Caddy or Nginx and initial protection
Published on 2026-11-18 · Author: Mikhail Gorbachev
// Fast route
This article belongs to the topic Servers and infrastructure.
Vaultwarden — the unofficial server implementation of Bitwarden, written in Rust. Official Bitwarden clients work with it: browser extensions, apps, the web vault, and the CLI bw. The project is licensed under AGPL-3.0, is not affiliated with Bitwarden, Inc., and is intended for individuals, families and small organizations. This article covers installing Vaultwarden 1.37.4 (release of 5 October 2026) in Docker behind a reverse proxy (Caddy or Nginx) and everything to do before the first real password appears in the vault: admin token, registration, the client’s real IP, fail2ban, two-factor authentication, backups and verification.
How Vaultwarden differs from the official server
Vaultwarden is a single container, by default using SQLite (MySQL and PostgreSQL are also supported), without the installation registration required by the official server.
What Vaultwarden includes:
- personal vaults, Send and attachments;
- organizations and collections, sharing, Emergency Access;
- organization groups and event log — both disabled by default (
ORG_GROUPS_ENABLED,ORG_EVENTS_ENABLED); - two-factor authentication, login via OpenID Connect, Directory Connector, part of organization policies.
What is not included: Bitwarden Secrets Manager and its bws utilities. The project maintainer has declined requests for support (discussion #3368, responses in 2023, 2024 and 2026). Therefore anything built on bws and the action bitwarden/sm-action will not work with Vaultwarden; machines will have to receive secrets via normal accounts and bw. More on choosing between Bitwarden cloud, the official server and Vaultwarden in the article “Password managers: Part 3 — Bitwarden and Vaultwarden”.
Entries are encrypted on the client; the master password is not sent to the server. But the server serves the web vault code to the browser, so a compromised server can alter that code and capture the master password when entered. Securing the server remains mandatory.
Why HTTPS is required
The web vault performs encryption in the browser via the Web Crypto API, and browsers provide this API only in a secure context: pages over HTTPS and on localhost. Over plain HTTP from an external address the web vault does not work at all.
Built-in TLS (via the Rocket web server) is not recommended by Vaultwarden documentation. TLS should be terminated at the reverse proxy, and the container should only listen on a local address. The project wiki recommends Caddy for newcomers: it automatically acquires and renews certificates.
Conditions for the examples: a server with Docker and Compose, domain vault.example.ru with an A record to 192.0.2.10, ports 80 and 443 open, project directory /opt/vaultwarden.
docker-compose.yml
services:
vaultwarden:
image: vaultwarden/server:1.37.4
container_name: vaultwarden
restart: unless-stopped
environment:
DOMAIN: "https://vault.example.ru"
SIGNUPS_ALLOWED: "true" # after creating accounts — "false"
INVITATIONS_ALLOWED: "true"
ADMIN_TOKEN: ${ADMIN_TOKEN} # Argon2 hash from .env file
LOG_FILE: "/data/vaultwarden.log"
TZ: "Europe/Moscow"
volumes:
- ./vw-data:/data
ports:
- "127.0.0.1:8000:80"127.0.0.1:8000:80— the container port is accessible only from the server itself. If you write just8000:80, Docker will open the port on all interfaces and add its own iptables rules bypassing ufw, and the server will become accessible over HTTP bypassing the proxy;./vw-data:/data— all data: thedb.sqlite3database, attachments,rsa_key*keys,config.json. This directory is what you back up;DOMAIN— the exact address users open the server at, with the schemehttps://. It is required behind a proxy: without it attachments, in particular, do not work;- the image version is pinned: with
latestthe server will update on anydocker compose pullwithout a fresh backup; LOG_FILEis needed for fail2ban;TZensures log timestamps match the host time;- WebSocket for instant sync works on the main port since version 1.29.0, a separate port 3012 is no longer required.
Admin token: Argon2 hash and dollar signs
Without ADMIN_TOKEN the /admin page is disabled. If a token is needed, set it not as plain text but as an Argon2 hash in PHC format. Vaultwarden can produce the hash itself:
docker run --rm -it vaultwarden/server:1.37.4 /vaultwarden hashThe command will ask for the password twice and print a line like $argon2id$v=19$m=65540,t=3,p=4$<salt>$<hash> (default parameters: about 64 MiB memory (65540 KiB), 3 iterations, 4 parallelism; password at least 8 characters; the --preset owasp key gives 19 MiB, 2 iterations, 1 parallelism). The original password (not the hash) is entered on the /admin page.
The main pitfall is the $ signs. Compose treats them as the start of a variable: from $argon2id$v=19$m=… it will try to substitute variables argon2id, v, m and will print warnings like The "argon2id" variable is not set. Defaulting to a blank string. The token is thus mangled, but Compose does not fail: the container will start and login to /admin will not work. Two correct ways:
in a
.envfile next todocker-compose.yml— put the value in single quotes,$signs are not doubled:bashADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$<salt>$<hash>'directly in the compose
environment— double each$:$$argon2id$$v=19$$m=65540,t=3,p=4$$<salt>$$<hash>.
Check before starting: docker compose config >/dev/null should not output warnings about unset variables (do not display the expanded configuration to the screen). Permissions on .env — chmod 600.
Settings saved via the admin UI are written to vw-data/config.json and override environment variables, so to disable the admin UI the token must be removed from both places. DISABLE_ADMIN_TOKEN=true is allowed only if there is a separate authentication in front of /admin at the proxy.
Registration and invitations
By default SIGNUPS_ALLOWED=true: any person who knows the address can create an account on your server. The procedure:
- Start the server with registration open, create your own account and admin accounts. While registration is open, do not leave the server unattended: anyone who finds the address can create an account. Or perform the first run with
SIGNUPS_ALLOWED: "false"and create accounts via invitations from/admin. - Set
SIGNUPS_ALLOWED: "false"and rundocker compose up -d. - Invite other users: a Vaultwarden admin — via
/admin(Users section), organization owners and admins — from the organization UI. This works even with registration closed, as long asINVITATIONS_ALLOWEDis enabled.
If SMTP is not configured, the invitee opens https://vault.example.ru/#/signup and registers exactly with the address to which the invitation was issued.
Pitfall: if SIGNUPS_DOMAINS_WHITELIST is set, the value of SIGNUPS_ALLOWED is ignored, and any address from the listed domains can register.
Caddy
A minimal Caddyfile based on the project wiki (/etc/caddy/Caddyfile):
vault.example.ru {
encode zstd gzip
header Strict-Transport-Security "max-age=31536000"
@admin {
path /admin*
not remote_ip 192.0.2.0/24
}
respond @admin 403
reverse_proxy 127.0.0.1:8000 {
header_up X-Real-IP {remote_host}
}
}Caddy will acquire the certificate itself and redirect HTTP to HTTPS. header_up X-Real-IP {remote_host} passes the client address to Vaultwarden. The @admin block restricts the admin page to everyone except the 192.0.2.0/24 network — replace with your office or VPN addresses. Apply: sudo caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy.
Nginx
Nginx version 1.25.1 or newer is required (the http2 on directive). The base is the reference HTTPS site config: it provides snippets/ssl.conf and certificate obtaining via certbot. The server block for Vaultwarden is built following the wiki example (/etc/nginx/conf.d/vault.example.ru.conf):
upstream vaultwarden-default {
server 127.0.0.1:8000;
keepalive 2;
}
map $http_upgrade $vw_connection {
default upgrade;
'' "";
}
server {
listen 80;
listen [::]:80;
server_name vault.example.ru;
location /.well-known/acme-challenge/ {
root /var/www/letsencrypt;
}
location / {
return 301 https://$host$request_uri;
}
}
server {
listen 443 ssl;
listen [::]:443 ssl;
http2 on;
server_name vault.example.ru;
ssl_certificate /etc/letsencrypt/live/vault.example.ru/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/vault.example.ru/privkey.pem;
include snippets/ssl.conf;
add_header Strict-Transport-Security "max-age=31536000" always;
client_max_body_size 525M;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $vw_connection;
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;
location / {
proxy_pass http://vaultwarden-default;
}
location /admin {
allow 192.0.2.0/24;
deny all;
proxy_pass http://vaultwarden-default;
}
}mapis named$vw_connectionto avoid conflict with$connection_upgradefrom the global config. For WebSocket it sendsConnection: upgrade, for regular requests it removes the header, and upstream connections are reused;proxy_set_headerat theserverlevel are inherited by bothlocationblocks since they have no overrides;client_max_body_size 525M— as in the wiki example: attachments and Send uploads go through the proxy;- security headers. Do not include the
security-headers.confsnippet from the reference config here. Vaultwarden itself sendsContent-Security-Policy,X-Frame-Options: SAMEORIGIN,X-Content-Type-Options,Referrer-PolicyandPermissions-Policy, andX-Frame-Options: DENYfrom the snippet will break FIDO2 WebAuthn: the wiki requiresSAMEORIGINfor it. Keep only HSTS on the proxy.
If long operations produce 504s, increase proxy_connect_timeout, proxy_send_timeout, proxy_read_timeout and send_timeout. Test and apply: sudo nginx -t && sudo systemctl reload nginx.
Real client IP and fail2ban
Vaultwarden takes the client address from the X-Real-IP header (parameter IP_HEADER) and uses it in logs and in rate-limiting login attempts (LOGIN_RATELIMIT_* and ADMIN_RATELIMIT_*). In version 1.37.4 the header is trusted only from proxies listed in IP_HEADER_TRUSTED_PROXIES; the default local — any non-global addresses — means proxies on the same host or in the same container network. If the proxy connects from a public address, list it explicitly.
Check: login with a wrong password and inspect the log.
grep 'Username or password is incorrect' /opt/vaultwarden/vw-data/vaultwarden.log | tail -1The line should contain your external address. If it shows 127.0.0.1 or the Docker bridge address, the proxy is not passing the header or its address is not in IP_HEADER_TRUSTED_PROXIES, and fail2ban will block the proxy itself.
fail2ban filters from the project wiki:
# /etc/fail2ban/filter.d/vaultwarden.local
[INCLUDES]
before = common.conf
[Definition]
failregex = ^.*?Username or password is incorrect\. Try again\. IP: <ADDR>\. Username:.*$
ignoreregex =# /etc/fail2ban/filter.d/vaultwarden-admin.local
[INCLUDES]
before = common.conf
[Definition]
failregex = ^.*Invalid admin token\. IP: <ADDR>.*$
ignoreregex =Jail (blocking rules):
# /etc/fail2ban/jail.d/vaultwarden.local
[vaultwarden]
enabled = true
port = 80,443
filter = vaultwarden
banaction = %(banaction_allports)s
logpath = /opt/vaultwarden/vw-data/vaultwarden.log
maxretry = 3
findtime = 14400
bantime = 14400
[vaultwarden-admin]
enabled = true
port = 80,443
filter = vaultwarden-admin
banaction = %(banaction_allports)s
logpath = /opt/vaultwarden/vw-data/vaultwarden.log
maxretry = 3
findtime = 14400
bantime = 14400The proxy here runs on the host, client connections go through the INPUT chain, and the default action fits. If the proxy itself runs in a container, traffic goes through FORWARD: the wiki suggests chain = FORWARD and banaction = iptables because Docker works with iptables, while recent fail2ban in Debian uses nftables by default.
If sudo fail2ban-client get vaultwarden backend shows systemd, add backend = pyinotify (or inotify) to both jails: otherwise logpath is ignored and the jail blocks nothing. The Vaultwarden wiki warns about this as a possible issue; check on your build with that command.
Test the filter and jail (in the output of fail2ban-client status vaultwarden your log file should be listed):
sudo fail2ban-regex /opt/vaultwarden/vw-data/vaultwarden.log /etc/fail2ban/filter.d/vaultwarden.local
sudo fail2ban-client status vaultwardenThe log grows without limits; add rotation in /etc/logrotate.d/vaultwarden:
/opt/vaultwarden/vw-data/vaultwarden.log {
weekly
rotate 8
compress
missingok
copytruncate
}Two-factor authentication
Vaultwarden supports five second-factor methods:
- Authenticator (TOTP) — an app with one-time codes. Codes depend on time, so time synchronization must work on the server (chrony or systemd-timesyncd);
- e-mail — requires SMTP configured;
- Duo — requires a Duo account and
DUO_*parameters; - YubiKey OTP — requires
YUBICO_CLIENT_IDandYUBICO_SECRET_KEYprovided by Yubico; - FIDO2 WebAuthn — hardware keys and platform keys; requires HTTPS and
X-Frame-Options: SAMEORIGIN.
Note the limitation of the CLI client: bw login can prompt for TOTP, e-mail and YubiKey OTP, but not FIDO2 or Duo. If an account has only FIDO2, bw logs in using an API key (bw login --apikey), after which the vault is still unlocked with the master password.
After enabling the first method save the recovery code (Settings → Security → Two-step login → View recovery code) outside the vault, for example printed. Enable at least two methods: e.g., two FIDO2 keys or a key plus TOTP. If a user loses all factors, a Vaultwarden admin can remove two-factor authentication from their account on /admin → Users; it must then be reconfigured immediately.
Backups
What to copy from vw-data according to the project wiki:
| What | Required | Why |
|---|---|---|
db.sqlite3 | yes | all accounts and encrypted records; copy only using SQLite tools |
attachments/ | yes | attachments |
sends/ | recommended | Send files, they are temporary |
config.json | recommended | admin UI settings, including SMTP password in plain text |
rsa_key* | recommended | token signing key; without it all users will be logged out |
icon_cache/ | no | recreated automatically |
You must not copy db.sqlite3 with cp on a running server: you can get an inconsistent file. The image does not contain sqlite3 or cron, but since version 1.32.1 there is a built-in command /vaultwarden backup. It makes a copy via VACUUM INTO and places it next to the database under the name db_YYYYMMDD_HHMMSS.sqlite3 (time in UTC).
Script /usr/local/sbin/vw-backup.sh that encrypts the archive using age with the public key (the private key is not stored on the server):
#!/bin/bash
set -euo pipefail
DATA=/opt/vaultwarden/vw-data
OUT=/var/backups/vaultwarden
TS=$(date +%Y%m%d-%H%M)
umask 077
mkdir -p "$OUT"
# 1. Consistent copy of the database using Vaultwarden.
# In the image the path in the message is relative ("data/..."), so the leading "/" is optional
f=$(docker exec vaultwarden /vaultwarden backup \
| sed -n "s|^Backup to '/\{0,1\}data/\(.*\)' was successful\$|\1|p")
[ -n "$f" ] || { echo "vaultwarden backup failed" >&2; exit 1; }
# 2. Archive: a copy of the DB, attachments, Send, keys, config.json.
# Write to a temporary file and rename only if the whole pipeline succeeds
cd "$DATA"
set -- "$f"
for p in attachments sends config.json rsa_key*; do
if [ -e "$p" ]; then set -- "$@" "$p"; fi
done
out="$OUT/vw-$TS.tar.gz.age"
tar -czf - "$@" | age -r '<age-public-key>' -o "$out.part"
mv "$out.part" "$out"
rm -f "$f"
# 3. Keep local copies for 14 days
find "$OUT" -name 'vw-*.tar.gz.age' -mtime +14 -deleteRun daily, for example /etc/cron.d/vaultwarden-backup:
30 3 * * * root /usr/local/sbin/vw-backup.shThe script stores copies only on the same server. Add sending the /var/backups/vaultwarden directory to another host (rclone, restic or rsync) and keep the age private key outside the server and outside the backup store: without it you cannot open backups. Rules from the wiki: daily copy, at least one offsite copy, backups encrypted, filesystem snapshots do not replace a SQLite-consistent DB copy. How to store encryption keys and other infrastructure secrets is covered in the article “Secure development: Part 2 — Secrets in code”.
Restore verification
Verify restores regularly on a separate machine where the age private key is available:
mkdir -p ~/vw-restore && cd ~/vw-restore
age -d -i <age-private-key-file> vw-20261118-0330.tar.gz.age | tar -xzf -
mv db_*.sqlite3 db.sqlite3
rm -f config.json # DOMAIN and SMTP of a test copy are not needed
sqlite3 db.sqlite3 'PRAGMA integrity_check; SELECT count(*) FROM users; SELECT count(*) FROM ciphers;'
# ok, then the number of users and records
docker run --rm -d --name vw-restore -v "$PWD":/data \
-e DOMAIN=http://localhost:8001 -p 127.0.0.1:8001:80 vaultwarden/server:1.37.4Open http://localhost:8001 (localhost is a secure context, HTTPS is not needed), log in, open a couple of records and an attachment. After testing: docker stop vw-restore && rm -rf ~/vw-restore.
For a real restore stop the service (docker compose down), delete old db.sqlite3-wal and db.sqlite3-shm if present — an outdated WAL file can corrupt the restored DB — unpack files into vw-data and start the service.
Post-install checks
From your computer:
# 1. HTTP redirects to HTTPS (status code 301 or 308)
curl -s -o /dev/null -w '%{http_code} %{redirect_url}\n' http://vault.example.ru/
# 2. service and DB respond
curl -s https://vault.example.ru/alive
# "2026-11-18T06:00:00.000000Z" — current server time
# 3. HSTS from the proxy and headers from Vaultwarden
curl -sI https://vault.example.ru/ | grep -iE '^(strict-transport|x-frame|content-security)'
# 4. container port from outside is closed
curl -s --connect-timeout 5 http://192.0.2.10:8000/ || echo closed
# 5. admin UI is closed to foreign addresses (from a network not in the list)
curl -s -o /dev/null -w '%{http_code}\n' https://vault.example.ru/admin
# 403In a browser:
- create a test record with an attachment: if it appears in the browser extension without manual sync, WebSocket works;
- try to register in a private window — the response will be “Registration not allowed or user already exists”;
- log into
/adminwith the original password and open Diagnostics: it shows the version, whether the client IP header was received, whether WebSocket is enabled, server time drift from NTP and settings overridden inconfig.json.
Publication checklist
- The container is published only on
127.0.0.1:8000, externally only ports 80 and 443 are open. -
DOMAINmatches the address in the browser and starts withhttps://. - Image version is pinned; update only after a fresh backup.
-
ADMIN_TOKENis an Argon2 hash,docker compose configwithout warnings,/adminrestricted by addresses or token disabled. -
SIGNUPS_ALLOWED=false,SIGNUPS_DOMAINS_WHITELISTnot set or intentionally restricted. - The log entry for a failed login shows the real client address; fail2ban blocks.
- All accounts have two second-factor methods.
- Daily encrypted backup, one offsite copy, restore verified.
- Log rotation configured, server time synchronized.
- The server itself is secured: SSH with keys, updates, firewall (see “Protecting a Linux server: Part 1 — UFW firewall”).
If the password manager is needed only by employees, restrict access to it via VPN. An internal network alone does not confer trust, so HTTPS, a second factor and fail2ban remain necessary even in that case.
// Similar task
If you are dealing with something similar
This article belongs to one of the main working topics. You can keep reading on the topic, go to the homepage to understand what I do, or open the service pages directly.
Article topic
Servers and infrastructure
VPS, Linux, web stack, migrations, hosting, databases, and core operations.
Typical tasks behind this topic
- Move a site or service to a new server
- Set up Linux, Nginx, databases, and backups
- Figure out why the system behaves unstably
// Next step
If you need help with this topic, not just another article, it is better to go straight to the service page. The homepage and topic collection stay available as secondary routes.
Open services// Reviews
Related reviews
The collaboration left an extremely positive impression, primarily because of the professionalism and the approach to resolving issues as they arose.
The experience of working together left an extremely positive impression, above all because of the professionalism and the approach to solving the issues that arose.
Jitsi Meet: a personal Zoom — setup in Docker and on a VPS
2025-11-11 · ★ 5/5
I needed to get n8n, Redis, and the database working. I had hired another contractor before and everything kept breaking. I hired Mikhail, and the next day everything was working quickly, like clockwork!
There was a task to get n8n, redis and the database working. I had previously ordered from another contractor, it kept breaking all the time. Ordered from Mikhail, the next day everything started working fast, like …
n8n installation on your VPS server. Configuration of n8n, Docker, AI, Telegram
2025-09-24 · ★ 5/5
Thank you for the fast and excellent work. Everything was done promptly and just as needed!
Thank you for the quick and good work. Everything was done promptly and as needed!
n8n installation on your VPS server. Configuration of n8n, Docker, AI, Telegram
2025-09-06 · ★ 5/5
Quick solution — I highly recommend Mikhail as a contractor! I tried to build a similar configuration myself and even followed AI advice, which ended up costing a lot of time and money (due to server downtime). So my advice: hire professionals — it's cheaper =) Thanks to Mikhail for his professionalism.
Quick fix for the problem, I recommend Mikhail as a contractor to everyone! I tried to assemble a similar configuration myself and following advice from neural networks, which resulted in a lot of wasted effort and …
n8n installation on your VPS server. Configuration of n8n, Docker, AI, Telegram.
2025-08-25 · ★ 5/5
Mikhail completed the setup of another VPS. He quickly and professionally bypassed certain hosting providers' restrictions.
Mikhail completed the setup of another VPS. Quickly, professionally bypassing certain limitations of hosting providers.
n8n installation on your VPS server. n8n, Docker, AI, Telegram setup
2025-08-12 · ★ 5/5
Great job, thank you! Mikhail is a true professional — I recommend him!
Excellent work, thank you! Mikhail is a professional in his field, I recommend him!
N8n installation on your VPS server. Setup of n8n, Docker, AI, Telegram
2025-07-03 · ★ 5/5
// Contact
Need help?
Get in touch with me and I'll help solve the problem
I reply within one business day (03:00-13:00 GMT)
Or leave a request here:
// Related