Deployn

Self-Host Vaultwarden with Docker, Caddy, and Fail2ban

Install Vaultwarden with Docker Compose: HTTPS through Caddy, an Argon2 admin token, disabled sign-ups, Fail2ban against brute force, and database backups.

Self-Host Vaultwarden with Docker, Caddy, and Fail2ban hero image
Contents
Tested with
Vaultwarden 1.37.5Caddy 2.11Fail2ban 1.1.0Docker 29.9Docker Compose 5.7Debian 13
Last checked on

With Vaultwarden you run your own password manager and still use the familiar Bitwarden apps. In this guide I install Vaultwarden with Docker Compose on a Debian 13 server, get the HTTPS certificate through Caddy, close open registration and let Fail2ban lock out attackers after a few failed attempts. At the end you back up the database with a single command.

What is Vaultwarden?

Vaultwarden is a server for the Bitwarden ecosystem, written in Rust. It speaks the same API as the official Bitwarden server, so all official Bitwarden clients work with it: browser extensions, desktop apps, the Android and iOS apps and the command line. The project used to be called bitwarden_rs. The source code is on GitHub under the AGPL-3.0.

Difference between Bitwarden and Vaultwarden

Bitwarden is the company behind the apps and the official server. You can self-host the Bitwarden server too, but it consists of several containers with an MSSQL or PostgreSQL database and needs a lot more memory. Vaultwarden is a single container with SQLite. On my test server it used about 11 MB of RAM at idle.

Vaultwarden is not an official Bitwarden product. Features that are part of the Bitwarden Premium plan, such as file attachments and emergency access, are free in Vaultwarden. The same goes for organizations with any number of members, which you use to share passwords with family or a team. You report problems to the Vaultwarden project, not to Bitwarden support.

Is Vaultwarden secure?

Encryption happens in the Bitwarden clients. The server only stores encrypted vaults and never sees your master password. Anyone who copies the database can’t do anything with it without your master password. The security of your instance therefore depends mostly on three things: a strong master password with two-step login, a server you keep up to date, and regular backups. This guide covers the last two.

Prerequisites

A server with DockerI use a VPS from Hetzner (CX23 with 2 vCPUs and 4 GB RAM) running Debian 13. Vaultwarden itself needs very little, a Raspberry Pi or the smallest VPS is enough. A VPS from netcup (affiliate link) works just as well. How to install Docker is covered in Docker basics.
A user with sudo rightsI run all Docker commands with sudo. I don’t recommend adding your user to the docker group: that amounts to root access without a password prompt. The reasons are in Docker basics.
A domainFor example {{domain}}. It needs an A record pointing to your server’s IP address. The Bitwarden apps only connect over HTTPS.
Open ports 80 and 443Caddy uses them to get the certificate and to accept requests.

If your server runs at home without a public IPv4 address, make it reachable with Pangolin. Vaultwarden on a Synology NAS has its own guide.

Step 1: Check domain and Docker

Connect to your server via SSH and check that the domain points to it:

Terminalbash
dig +short {{domain}}

The output must be your server’s IP address. If it is empty or shows a different address, the DNS record hasn’t arrived yet. Wait before you continue, otherwise the Let’s Encrypt certificate will fail.

Then check Docker:

Terminalbash
sudo docker --version
sudo docker compose version

For me that was Docker 29.9.3 and Docker Compose 5.7.1.

Step 2: Docker network and Caddy

Caddy and Vaultwarden live in separate Compose projects and find each other through a shared Docker network. I call it proxy:

Terminalbash
sudo docker network create proxy

If Caddy already runs as described in my Caddy guide, skip the rest of this step. Otherwise set up Caddy now:

Terminalbash
mkdir -p ~/caddy/data ~/caddy/config
cd ~/caddy
nano compose.yaml
~/caddy/compose.yamlyaml
services:
  caddy:
    image: caddy:2.11
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./data:/data
      - ./config:/config
    networks:
      - proxy

networks:
  proxy:
    external: true

The Caddyfile gets a block for Vaultwarden:

Terminalbash
nano ~/caddy/Caddyfile
~/caddy/Caddyfilecaddy
{{domain}} {
	reverse_proxy vaultwarden:80 {
		header_up X-Real-IP {remote_host}
	}
}
  • vaultwarden:80 is the container name and the port Vaultwarden listens on inside the container.
  • header_up X-Real-IP {remote_host} passes on the visitor’s real IP address. Vaultwarden reads this header. Without the line, my log showed IP: 172.18.0.3 for every failed attempt, which is the address of the Caddy container. Fail2ban would then have banned Caddy and with it every visitor.

Caddy is started in the next step together with Vaultwarden.

Step 3: Vaultwarden with Docker Compose

Create a directory for Vaultwarden:

Terminalbash
mkdir -p ~/vaultwarden/vw-data
cd ~/vaultwarden
nano compose.yaml
~/vaultwarden/compose.yamlyaml
services:
  vaultwarden:
    image: vaultwarden/server:1.37.5
    container_name: vaultwarden
    restart: unless-stopped
    user: "1000:1000"
    environment:
      DOMAIN: "https://{{domain}}"
      TZ: "Europe/Berlin"
    volumes:
      - ./vw-data:/data
    networks:
      - proxy

networks:
  proxy:
    external: true
  • image: I pin the version. With latest an update arrives unnoticed on the next pull, and for a password manager I want a backup first. The current version is listed in the releases on GitHub.
  • user: Vaultwarden runs with your user ID instead of root. Find it with id -u and id -g. The first user on Debian and Ubuntu usually has 1000.
  • DOMAIN: The full address including https://. Vaultwarden needs it for links in emails, for file attachments and for security keys (WebAuthn).
  • TZ: The time zone for the timestamps in the log. You don’t need extra mounts for /etc/localtime and /etc/timezone. In my test, sudo docker exec vaultwarden date showed the correct time with TZ alone.
  • No ports: Vaultwarden is only reachable through Caddy. There is no way around HTTPS from the outside.

The file has no version: field anymore. Docker Compose ignores it and only prints a warning. You also don’t need WEBSOCKET_ENABLED anymore: since version 1.29, live notifications run over the normal port 80.

The vw-data folder must belong to your user, otherwise Vaultwarden can’t create the database:

Terminalbash
sudo chown -R 1000:1000 ~/vaultwarden/vw-data

Now start Vaultwarden and then Caddy:

Terminalbash
cd ~/vaultwarden
sudo docker compose up -d
cd ~/caddy
sudo docker compose up -d

After about 20 seconds, sudo docker ps shows both containers as Up. The vw-data folder now holds the database db.sqlite3 and the key rsa_key.pem.

Step 4: Create your account

Open https://{{domain}} in your browser. You’ll see Vaultwarden’s web interface, the web vault. Click “Create account”, enter your email address and choose a master password.

The master password is the key to your vault. If you forget it, nobody can recover your data, not even you as the admin. Write it down on paper and keep it somewhere safe.

In the Bitwarden apps, choose “Self-hosted” as the server when you log in and enter https://{{domain}} as the server URL.

Step 5: Disable sign-ups and set up the admin panel

Right now anyone who knows your address can create an account. You switch that off. At the same time you set up the admin panel at https://{{domain}}/admin. That’s where you manage users, send invitations and configure email.

Create the admin token

The admin panel is protected by a token. Vaultwarden ships a command that hashes your admin password with Argon2. You don’t need an extra package:

Terminalbash
sudo docker exec -it vaultwarden /vaultwarden hash

The command asks for the password twice and then prints one line:

ADMIN_TOKEN='$argon2id$v=19$m=65540,t=3,p=4$KtZIn7Gr7tysnCZT61E+uAgm0YtVcKJruHeKLDoxFrs$IOTelZ9PeeUK2hzAd+3B3rWoeY7tw+YqamWs6XPnWL8'

The -it is required because the command needs a terminal for the password prompt. Without it, it fails with No such device or address.

Copy the whole line into a .env file next to compose.yaml:

Terminalbash
nano ~/vaultwarden/.env
chmod 600 ~/vaultwarden/.env

In the .env file the single quotes are already in place, so Docker Compose takes the $ signs literally. If you put the hash directly into compose.yaml, you have to write every $ as $$, otherwise Compose tries to turn them into variables.

Extend the Compose file

Open compose.yaml and add env_file, SIGNUPS_ALLOWED and the two log variables:

~/vaultwarden/compose.yamlyaml
services:
  vaultwarden:
    image: vaultwarden/server:1.37.5
    container_name: vaultwarden
    restart: unless-stopped
    user: "1000:1000"
    env_file: .env
    environment:
      DOMAIN: "https://{{domain}}"
      TZ: "Europe/Berlin"
      SIGNUPS_ALLOWED: "false"
      LOG_FILE: "/data/vaultwarden.log"
      LOG_LEVEL: "warn"
    volumes:
      - ./vw-data:/data
    networks:
      - proxy

networks:
  proxy:
    external: true
  • SIGNUPS_ALLOWED: "false": Nobody can register on their own anymore. You invite new users from the admin panel.
  • LOG_FILE and LOG_LEVEL: Vaultwarden also writes warnings and errors to vw-data/vaultwarden.log. Failed logins show up there as ERROR. Fail2ban reads this file later.

Then recreate the container:

Terminalbash
cd ~/vaultwarden
sudo docker compose up -d

Log in at https://{{domain}}/admin with your plain-text password, not the hash. If you now try to create a new account, Vaultwarden answers with “Registration not allowed or user already exists”.

Under “SMTP Email Settings” in the admin panel you enter a mail server. Vaultwarden then sends invitations, new-login notifications and two-step login codes by email.

Step 6: Turn on two-step login

In the web vault under “Settings” → “Security” → “Two-step login” you’ll find the methods Vaultwarden supports: authenticator app (TOTP), security keys via FIDO2/WebAuthn, YubiKey OTP, Duo and email. An authenticator app such as Aegis or 2FAS is the easiest start.

A hardware key is stronger, for example a YubiKey 5 NFC (Amazon affiliate link). It works over USB on a computer and over NFC on a phone. Set up two keys and store the second one separately so you aren’t locked out if you lose one. Keep the recovery code Vaultwarden shows you during setup together with your master password.

Step 7: Fail2ban against brute-force attacks

Fail2ban reads Vaultwarden’s log, counts failed attempts per IP address and bans attackers in the firewall for a while. I install Fail2ban directly on the server, not in a container:

Terminalbash
sudo apt install -y fail2ban

Filters

The filter describes which lines count as a failed attempt. This is what a wrong login looks like in the log:

[2026-11-15 16:17:55.260][vaultwarden::api::identity][ERROR] Username or password is incorrect. Try again. IP: 203.0.113.7. Username: nobody@example.com.

Create the filter for the normal login:

Terminalbash
sudo nano /etc/fail2ban/filter.d/vaultwarden.local
/etc/fail2ban/filter.d/vaultwarden.localini
[INCLUDES]
before = common.conf

[Definition]
failregex = ^.*?Username or password is incorrect\. Try again\. IP: <ADDR>\. Username:.*$
ignoreregex =

And a second one for the admin panel. There the line reads Invalid admin token. IP: 203.0.113.7:

Terminalbash
sudo nano /etc/fail2ban/filter.d/vaultwarden-admin.local
/etc/fail2ban/filter.d/vaultwarden-admin.localini
[INCLUDES]
before = common.conf

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

Jail

The jail connects filter, log file and ban duration:

Terminalbash
sudo nano /etc/fail2ban/jail.d/vaultwarden.local
/etc/fail2ban/jail.d/vaultwarden.localini
[vaultwarden]
enabled = true
backend = auto
port = http,https
filter = vaultwarden
logpath = /home/{{username}}/vaultwarden/vw-data/vaultwarden.log
maxretry = 5
findtime = 1h
bantime = 24h
banaction = iptables-multiport
chain = DOCKER-USER

[vaultwarden-admin]
enabled = true
backend = auto
port = http,https
filter = vaultwarden-admin
logpath = /home/{{username}}/vaultwarden/vw-data/vaultwarden.log
maxretry = 3
findtime = 10h
bantime = 7d
banaction = iptables-multiport
chain = DOCKER-USER
  • maxretry, findtime, bantime: Anyone who enters a wrong password five times within an hour is banned for 24 hours. For the admin panel it’s three attempts in ten hours and a seven-day ban.
  • backend = auto: Debian 13 reads the SSH jail from the systemd journal. Vaultwarden writes to a file, though. This line makes sure Fail2ban reads the file from logpath for these jails.
  • chain = DOCKER-USER: Requests to Docker containers bypass the normal INPUT chain. A ban there would have no effect on Caddy. Docker checks the DOCKER-USER chain before its own rules, so that’s where the ban works.
  • logpath: The path on the server, not inside the container. Replace {{username}} with your username.

Before restarting Fail2ban, test the filter against the real log. You need at least one failed attempt for that, so log in once with a wrong password:

Terminalbash
sudo fail2ban-regex /home/{{username}}/vaultwarden/vw-data/vaultwarden.log /etc/fail2ban/filter.d/vaultwarden.local

The output must show at least one match under Failregex. Then restart Fail2ban:

Terminalbash
sudo systemctl restart fail2ban
sudo fail2ban-client status
Status
|- Number of jail:	3
`- Jail list:	sshd, vaultwarden, vaultwarden-admin

Test the ban

Enter a wrong password five times in the web vault. After that the page stops loading. For me the next request timed out, and the status showed my address:

Terminalbash
sudo fail2ban-client status vaultwarden
Status for the jail: vaultwarden
|- Filter
|  |- Currently failed:	0
|  |- Total failed:	5
|  `- File list:	/home/deployn/vaultwarden/vw-data/vaultwarden.log
`- Actions
   |- Currently banned:	1
   |- Total banned:	1
   `- Banned IP list:	203.0.113.7

This lifts the ban again:

Terminalbash
sudo fail2ban-client set vaultwarden unbanip YOUR-IP

Step 8: Backup

A complete backup needs the whole ~/vaultwarden/vw-data folder:

  • db.sqlite3: The database with all encrypted vaults.
  • rsa_key.pem: The key Vaultwarden uses to sign logins. Without it, all clients have to log in again after a restore.
  • attachments and sends: File attachments and files from Bitwarden Send, once there are any.
  • config.json: The settings from the admin panel, if you saved anything there.

Add compose.yaml and .env to that. The .env file contains the hash of your admin password, so treat the backup accordingly.

You shouldn’t simply copy an SQLite file that is being written to. Vaultwarden makes a clean copy while it’s running:

Terminalbash
cd ~/vaultwarden
sudo docker compose exec vaultwarden /vaultwarden backup
Backup to 'data/db_20261115_151902.sqlite3' was successful

The copy lands in vw-data and goes into your backup with the folder. To do this every night, add two lines to the root crontab with sudo crontab -e. The first creates a copy at 3 a.m., the second deletes copies older than 14 days:

Terminalbash
0 3 * * * docker compose -f /home/{{username}}/vaultwarden/compose.yaml exec -T vaultwarden /vaultwarden backup
15 3 * * * find /home/{{username}}/vaultwarden/vw-data -name 'db_*.sqlite3' -mtime +14 -delete

-T matters because cron has no terminal. Then move the folder to another device with a backup tool like Duplicati. A backup on the same server doesn’t help you when the server fails.

Update Vaultwarden

New versions often fix security issues. Watch the releases on GitHub to get notified. This is how you update:

  1. Read the release notes of the new version.
  2. Create a backup with sudo docker compose exec vaultwarden /vaultwarden backup.
  3. Change the tag in compose.yaml, for example from 1.37.5 to the new version.
  4. Pull the image and recreate the container:
Terminalbash
cd ~/vaultwarden
sudo docker compose pull
sudo docker compose up -d

sudo docker compose logs vaultwarden shows whether the start worked. Vaultwarden migrates the database on its own at startup.

Frequently asked questions

Is Vaultwarden free?

Yes. Vaultwarden is open source under the AGPL-3.0. Features from the Bitwarden Premium plan, such as file attachments and emergency access, are included. You only pay for the server and the domain.

How many resources does Vaultwarden need?

Very few. On my test server Vaultwarden used about 11 MB of memory at idle, Caddy about 17 MB. A Raspberry Pi or the smallest VPS is enough.

Can I use the official Bitwarden apps?

Yes. When logging in to the app or browser extension, choose "Self-hosted" as the server and enter your address with https://.

Can I use Vaultwarden without a domain?

Only with limits. The Bitwarden clients and the web vault need HTTPS with a valid certificate. Without a public domain you can run Caddy with an internal certificate, but then you have to mark it as trusted on every device.

What happens if my server goes down?

The Bitwarden apps keep an encrypted copy of your vault on the device. You can still read your passwords but can't change anything until the server is back. That's why a backup on another device matters.

As an Amazon Associate I earn from qualifying purchases.

Share
XRedditEmail
Back to all posts

Changelog

  1. Updated to Vaultwarden 1.37.5: Compose without the version field, DOMAIN set, admin token from the built-in vaultwarden hash command in a .env file, sign-ups disabled with SIGNUPS_ALLOWED, Fail2ban on the host with the DOCKER-USER chain, backups with vaultwarden backup, and new sections on two-step login, updates and FAQ.

Related articles

Comments