Skip to content

// Engineering Log

Secrets and Zero Trust: Part 2 — Vaultwarden behind Caddy or Nginx and initial protection

Published on 2026-11-18 · Author:

// 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

yaml
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 just 8000: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: the db.sqlite3 database, attachments, rsa_key* keys, config.json. This directory is what you back up;
  • DOMAIN — the exact address users open the server at, with the scheme https://. It is required behind a proxy: without it attachments, in particular, do not work;
  • the image version is pinned: with latest the server will update on any docker compose pull without a fresh backup;
  • LOG_FILE is needed for fail2ban; TZ ensures 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:

bash
docker run --rm -it vaultwarden/server:1.37.4 /vaultwarden hash

The 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 .env file next to docker-compose.yml — put the value in single quotes, $ signs are not doubled:

    bash
    ADMIN_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:

  1. 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.
  2. Set SIGNUPS_ALLOWED: "false" and run docker compose up -d.
  3. 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 as INVITATIONS_ALLOWED is 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):

caddy
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):

nginx
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;
    }
}
  • map is named $vw_connection to avoid conflict with $connection_upgrade from the global config. For WebSocket it sends Connection: upgrade, for regular requests it removes the header, and upstream connections are reused;
  • proxy_set_header at the server level are inherited by both location blocks 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.conf snippet from the reference config here. Vaultwarden itself sends Content-Security-Policy, X-Frame-Options: SAMEORIGIN, X-Content-Type-Options, Referrer-Policy and Permissions-Policy, and X-Frame-Options: DENY from the snippet will break FIDO2 WebAuthn: the wiki requires SAMEORIGIN for 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.

bash
grep 'Username or password is incorrect' /opt/vaultwarden/vw-data/vaultwarden.log | tail -1

The 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:

ini
# /etc/fail2ban/filter.d/vaultwarden.local
[INCLUDES]
before = common.conf

[Definition]
failregex = ^.*?Username or password is incorrect\. Try again\. IP: <ADDR>\. Username:.*$
ignoreregex =
ini
# /etc/fail2ban/filter.d/vaultwarden-admin.local
[INCLUDES]
before = common.conf

[Definition]
failregex = ^.*Invalid admin token\. IP: <ADDR>.*$
ignoreregex =

Jail (blocking rules):

ini
# /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  = 14400

The 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):

bash
sudo fail2ban-regex /opt/vaultwarden/vw-data/vaultwarden.log /etc/fail2ban/filter.d/vaultwarden.local
sudo fail2ban-client status vaultwarden

The 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_ID and YUBICO_SECRET_KEY provided 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:

WhatRequiredWhy
db.sqlite3yesall accounts and encrypted records; copy only using SQLite tools
attachments/yesattachments
sends/recommendedSend files, they are temporary
config.jsonrecommendedadmin UI settings, including SMTP password in plain text
rsa_key*recommendedtoken signing key; without it all users will be logged out
icon_cache/norecreated 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):

bash
#!/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 -delete

Run daily, for example /etc/cron.d/vaultwarden-backup:

30 3 * * * root /usr/local/sbin/vw-backup.sh

The 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:

bash
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.4

Open 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:

bash
# 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
# 403

In 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 /admin with 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 in config.json.

Publication checklist

  • The container is published only on 127.0.0.1:8000, externally only ports 80 and 443 are open.
  • DOMAIN matches the address in the browser and starts with https://.
  • Image version is pinned; update only after a fresh backup.
  • ADMIN_TOKEN is an Argon2 hash, docker compose config without warnings, /admin restricted by addresses or token disabled.
  • SIGNUPS_ALLOWED=false, SIGNUPS_DOMAINS_WHITELIST not 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

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 …

christ_media

n8n installation on your VPS server. Configuration of n8n, Docker, AI, Telegram

2025-09-24 · ★ 5/5

Experienced buyer

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 …

ladohinpy

n8n installation on your VPS server. Configuration of n8n, Docker, AI, Telegram.

2025-08-25 · ★ 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:

Confirm that you are not a bot.

Write and get a quick reply