Chapter 1: Initial Setup and Key Creation

This stage establishes your key pair and trust level.

Create Master Key Pair incl. encryption subkey

gpg --full-gen-key

On the following dialog you use ECC algorithms (ed25519 for signing, cv25519 for encryption) and chose option (9) ECC (sign, encryption) standard. You set an expiration date (e.g., 5 years) for forward compatibility. Finally you choose a strong, unique passphrase!

Create signing Subkey

Do not use the Master Key for signing in your daily work. Create an additional separate subkey for signing (S).

gpg --edit-key <KEY-ID>

gpg\> addkey

You type addkey and then option (10) ECC (only sign).

Then you check the generated Master Key including the subkeys

gpg --list-secret-keys

sec   ed25519 2025-12-25 [SC] [verfällt: 2030-12-24]
	C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid        [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
ssb   cv25519 2025-12-25 [E] [verfällt: 2030-12-24]
ssb   ed25519 2025-12-25 [S] [verfällt: 2030-12-24]

sec: The secret master key (sec) is for Signing and Certification (SC).

KEY-ID: C957EA3BD909D1D3BA594D2CE14085D8197A0018.

ssb: The first subkey (ssb) is for encryption (E).

ssb: The second subkey (ssb) is for signing (S).

All Keys expire at 2030-12-24.

Set Trust Level

As you can see above my trust level is already ultimate. So here just for completion the command how to set the trust level on your keys.

Mark your own key as ultimately trusted so GnuPG relies on your certifications (key separation, subkey creation).

gpg --edit-key <KEY-ID>

gpg\> trust

Then type trust and select option 5 (ultimate).

Chapter 2: Security and Hardening

This stage prepares the necessary backups and secures the master key.

Backup the Master Key and generate Revocation Certificate

Do this immediately and store the fullback-up file and the revocation certificate file offline.

gpg --export-secret-keys --armor <KEY-ID> > fullbackup.asc	

gpg --output revocation.asc --gen-revoke <KEY-ID>

Implement Key Separation

Check the key setup again to identify clearly your 3 Key-IDs. Here we use the long format command.

gpg --list-secret-keys --keyid-format long

sec   ed25519/E14085D8197A0018 2025-12-25 \[SC] \[verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid              [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)

ssb   cv25519/AF0CB4F423538B80 2025-12-25 [E] [verfällt: 2030-12-24]

ssb   ed25519/56025D0BF8BF5B2F 2025-12-25 [S] [verfällt: 2030-12-24]

Master Key-ID (SC): E14085D8197A0018

Subkey 1-Key-ID (E): AF0CB4F423538B80

Subkey 2-Key-ID (S): 56025D0BF8BF5B2F

The goal is: Remove the Master Secret Key (sec) from your local machine using the delete command, turning it into a stub (sec#). This protects the core of your identity from malware. Keep both Subkeys for daily encryption (E) and signing (S).

Before you run the delete command, you must be 100% certain your backup file is valid. If you delete the master key now without a verified backup, you are back to the fatal „lost key“ situation. Run the following 2 checks.

Check 1:

gpg --list-packets /path/to/fullbackup.asc | grep "secret key packet"

:secret key packet:

The output must! show:

:secret key packet:

Check 2:

gpg --list-packets /path/to/fullbackup.asc

off=0 ctb=94 tag=5 hlen=2 plen=134
:secret key packet:
	version 4, algo 22, created 1766645842, expires 0
	pkey[0]: [80 bits] ed25519 (1.3.6.1.4.1.11591.15.1)
	pkey[1]: [263 bits]
	iter+salt S2K, algo: 7, SHA1 protection, hash: 2, salt: E5DD0BCA22F746A5
	protect count: 65011712 (255)
	protect IV:  d6 b2 c9 5d e2 3f 05 d3 35 fb cc 7b 87 41 cf f5
	skey[2]: [v4 protected]
	keyid: E14085D8197A0018
# off=136 ctb=b4 tag=13 hlen=2 plen=44
:user ID packet: "Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)"
# off=182 ctb=88 tag=2 hlen=2 plen=153
:signature packet: algo 22, keyid E14085D8197A0018
	version 4, created 1766645842, md5len 0, sigclass 0x13
	digest algo 10, begin of digest f0 54
	hashed subpkt 33 len 21 (issuer fpr v4 C957EA3BD909D1D3BA594D2CE14085D8197A0018)
	hashed subpkt 2 len 4 (sig created 2025-12-25)
	hashed subpkt 27 len 1 (key flags: 03)
	hashed subpkt 9 len 4 (key expires after 5y0d0h0m)
	hashed subpkt 11 len 4 (pref-sym-algos: 9 8 7 2)
	hashed subpkt 34 len 1 (pref-aead-algos: 2)
	hashed subpkt 21 len 5 (pref-hash-algos: 10 9 8 11 2)
	hashed subpkt 22 len 3 (pref-zip-algos: 2 3 1)
	hashed subpkt 30 len 1 (features: 07)
	hashed subpkt 23 len 1 (keyserver preferences: 80)
	subpkt 16 len 8 (issuer key ID E14085D8197A0018)
	data: [256 bits]
	data: [255 bits]
# off=337 ctb=9c tag=7 hlen=2 plen=139
:secret sub key packet:
	version 4, algo 18, created 1766645842, expires 0
	pkey[0]: [88 bits] cv25519 (1.3.6.1.4.1.3029.1.5.1)
	pkey[1]: [263 bits]
	pkey[2]: [32 bits]
	iter+salt S2K, algo: 7, SHA1 protection, hash: 2, salt: 2DE27015BEF91567
	protect count: 65011712 (255)
	protect IV:  f8 13 05 2b 8d a0 97 0d 22 99 3b b5 c3 62 43 be
	skey[3]: [v4 protected]
	keyid: AF0CB4F423538B80
# off=478 ctb=88 tag=2 hlen=2 plen=126
:signature packet: algo 22, keyid E14085D8197A0018
	version 4, created 1766645842, md5len 0, sigclass 0x18
	digest algo 10, begin of digest fc 2e
	hashed subpkt 33 len 21 (issuer fpr v4 C957EA3BD909D1D3BA594D2CE14085D8197A0018)
	hashed subpkt 2 len 4 (sig created 2025-12-25)
	hashed subpkt 27 len 1 (key flags: 0C)
	hashed subpkt 9 len 4 (key expires after 5y0d0h0m)
	subpkt 16 len 8 (issuer key ID E14085D8197A0018)
	data: [254 bits]
	data: [256 bits]
# off=606 ctb=9c tag=7 hlen=2 plen=134
:secret sub key packet:
	version 4, algo 22, created 1766645997, expires 0
	pkey[0]: [80 bits] ed25519 (1.3.6.1.4.1.11591.15.1)
	pkey[1]: [263 bits]
	iter+salt S2K, algo: 7, SHA1 protection, hash: 2, salt: 09FD8782B037DC77
	protect count: 65011712 (255)
	protect IV:  e3 fc 51 3f 7d 35 f8 78 a9 43 72 fe 73 f9 82 16
	skey[2]: [v4 protected]
	keyid: 56025D0BF8BF5B2F
# off=742 ctb=88 tag=2 hlen=2 plen=245
:signature packet: algo 22, keyid E14085D8197A0018
	version 4, created 1766645997, md5len 0, sigclass 0x18
	digest algo 10, begin of digest fe 58
	hashed subpkt 33 len 21 (issuer fpr v4 C957EA3BD909D1D3BA594D2CE14085D8197A0018)
	hashed subpkt 2 len 4 (sig created 2025-12-25)
	hashed subpkt 27 len 1 (key flags: 02)
	hashed subpkt 9 len 4 (key expires after 5y0d0h0m)
	subpkt 16 len 8 (issuer key ID E14085D8197A0018)
	subpkt 32 len 117 (signature: v4, class 0x19, algo 22, digest algo 10)
	data: [256 bits]
	data: [256 bits]

This is the expected output: You expect 3 packets most important is the :secret key packet:

Master Key package:

:secret key packet: secret master key packet with KeyID: E14085D8197A0018

:signature packet: This show the signature packet belonging to your secret key packet and issuer key ID E14085D8197A0018

Subkey 1 Key package:

:secret sub key packet: secret subkey packet with KeyID: AF0CB4F423538B80

:signature packet: This show the signature packet belonging to your secret sub key packet and issuer key ID E14085D8197A0018

Subkey 2 Key package:

:secret sub key packet: secret subkey packet with keyid: 56025D0BF8BF5B2F

:signature packet: This show the signature packet belonging to your secret sub key packet and issuer key ID E14085D8197A0018

Only in case :secret key packet: is available proceed!

GnuPG does not have a single command like —delete-only-master key. Instead, the standard „clean“ way to do this is a three-step process.

Step 1: Export ONLY your Secret Subkeys in a temporary subkeys-only file

gpg --export-secret-subkeys --armor E14085D8197A0018 > subkeys-only.asc

Step 2: Delete the current Secret Key (complete wipe) from your MacBook

gpg --delete-secret-keys E14085D8197A0018

Step 3: Import the Secret Subkeys

gpg --import subkeys-only.asc

Step 4: Remove the temporary subkeys-only file

rm subkeys-only.asc

Then check your local setup.

gpg --list-secret-keys

sec#  ed25519 2025-12-25 [SC] [verfällt: 2030-12-24]
      C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid        [ ultimativ ] Patrick Rottlaender <patrick@rottlaender.eu>
ssb   cv25519 2025-12-25 [E] [verfällt: 2030-12-24]
ssb   ed25519 2025-12-25 [S] [verfällt: 2030-12-24]

Here you see your Master Secret Key (sec) has been removed from your local machine and turning it into a stub (sec#).

Chapter 3: Reset and Restore (Scenario: Start From Scratch)

These steps show how to completely wipe your local key and restore it using the backup.

Delete Complete Key Set (Local Wipe)

Use both commands to ensure both the remaining subkeys and the Public Key are completely removed from your local keyring before restoring.

gpg --delete-secret-keys <KEY-ID> (Deletes subkeys/stubs)
gpg --delete-keys <KEY-ID> (Deletes public key)

Import Complete Key Set (Restore)

Use the verified backup file created in Step 2 to fully restore your Master Key and Subkeys back to the pre-separation state.

First you check the fullback file before you run the import.

#Check the backupfile
gpg --show-keys /path/to/fullbackup.asc

sec   ed25519 2025-12-25 [SC] [verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid        [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
ssb   cv25519 2025-12-25 [E] [verfällt: 2030-12-24]
ssb   ed25519 2025-12-25 [S] [verfällt: 2030-12-24]

#run the import
gpg --import /path/to/fullbackup.asc

Chapter 4: Useful commands

List public keys

gpg –list-keys

pub   ed25519 2025-12-25 [SC] [verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid        [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
sub   cv25519 2025-12-25 [E] [verfällt: 2030-12-24]
sub   ed25519 2025-12-25 [S] [verfällt: 2030-12-24]

List secret keys

gpg –list-secret-keys

sec   ed25519 2025-12-25 [SC] [verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid        [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
ssb   cv25519 2025-12-25 [E] [verfällt: 2030-12-24]
ssb   ed25519 2025-12-25 [S] [verfällt: 2030-12-24]

List public keys showing all KeyIDs

gpg --list-keys --keyid-format long

pub   ed25519/E14085D8197A0018 2025-12-25 [SC] [verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid              [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
sub   cv25519/AF0CB4F423538B80 2025-12-25 [E] [verfällt: 2030-12-24]
sub   ed25519/56025D0BF8BF5B2F 2025-12-25 [S] [verfällt: 2030-12-24]

List secret keys showing all KeyIDs

gpg --list-secret-keys --keyid-format long

sec   ed25519/E14085D8197A0018 2025-12-25 [SC] [verfällt: 2030-12-24]
	  C957EA3BD909D1D3BA594D2CE14085D8197A0018
uid              [ ultimativ ] Patrick Rottlaender [patrick@rottlaender.eu](mailto:patrick@rottlaender.eu)
ssb   cv25519/AF0CB4F423538B80 2025-12-25 [E] [verfällt: 2030-12-24]
ssb   ed25519/56025D0BF8BF5B2F 2025-12-25 [S] [verfällt: 2030-12-24]

Master Key (SC): E14085D8197A0018

Subkey 1 (E): AF0CB4F423538B80

Subkey 2 (S): 56025D0BF8BF5B2F

Encrypt

gpg -e -r patrick@rottlaender.eu file.txt

Decrypt

gpg -d file.txt.gpg > file.txt

Sign & Encrypt

gpg -se -r recipient@email.com file.txt

Decrypt & Verify

#shows the signature status automatically
gpg -d file.txt.gpg

Chapter 5: General note

ed25519 and cv25519 are algorithms based on Curve25519

ed25519 (Master Key & Signing Subkey)

Feature Description

Full Name: Edwards-curve Digital Signature Algorithm over Curve25519.

Cryptographic Role: Digital Signing and Verification. It is designed to create a mathematical signature that proves the origin (authenticity) and integrity of a message or file.

GnuPG Use: Used for your Master Key ([C]) to certify other keys, and your Signing Subkey ([S]) to sign emails or commits.

Security Property: It is highly resistant to various side-channel attacks and has a very reliable, straightforward implementation.

cv25519 (Encryption Subkey)

Feature Description

Full Name: Curve25519 variant used for Key Exchange.

Cryptographic Role: Key Exchange and Encryption. It is designed for the Diffie-Hellman (DH) key exchange process, which allows two parties to securely establish a shared secret (like a session key) over an insecure channel.

GnuPG Use: Used for your Encryption Subkey ([E]). It enables others to encrypt data to you, and you to decrypt it using the established session key.

Security Property: Highly efficient and designed specifically for confidential (private) communication.

Modern GnuPG key management strictly separates cryptographic roles signing and encryption for security reasons:

• You sign with ed25519: To prove you are the one you are (in my case I am Patrick!).
• You encrypt with cv25519: To ensure privacy.

This separation of duties means if one subkey were ever theoretically broken, it wouldn’t automatically compromise the function of the other key. For example, if your signing key (ed25519) was compromised, your ability to decrypt past files or conversations (protected by cv25519) would remain secure.

Prepare your Server

Before we start we need to prepare the server. In this step we create the environment to manage the vaultwarden instance. Login to your server using your standard User (not root).

Basic requirements

Login to your server with SSH and authenticate with keys. Never use simple password authentication. You must create a private and a public SSH key-pair on your Host Machine and copy only the public SSH key to your Remote Server. Keep your private key safe on your Host machine. Then copy your public key to your Remote Server and configure your ssh-deamon on your Remote Server. Disable password authentication and root login in your configuration on your Remote Server. How all this works is very good explained on Linuxize.com.

You must ensure that SSL certificates for your server are installed. I use free LetsEncrypt certificates and certbot to install and renew my certificates on the system. Therefore pls. read on my Digitaldocblog in the Article SSL Certificates with Lets Encrypt and certbot on a Linux Server . Here you find a very detailed description of how you can do this .

You must ensure that docker and docker-compose is installed on your system. Therefore pls. read on my Digitaldocblog a very detailed description of how you can do this in the Article Containerize a nodejs app with nginx. You should read the following chapters:

• Prepare the System for secure Downloads from Docker
• Install Docker from Docker Resources
• Install standalone docker-compose from Docker Resources
  

Make sure that your server is running behind a firewall. In my case I have a virtual server and I am responsible for server security. Therefore I install and configure a firewall on my system.

Before you configure the firewall be sure that your ssh service is running and on which port your ssh service is running. This is important to know because you don’t want to lock yourself out. First you check if the ssh service is running with systemctl and then on which port ssh is running using netstat. If netstat is not installed on your system you can do this with apt.

#control ssh status
sudo systemctl status ssh

#check ssh port
sudo netstat -tulnp | grep ssh

#check if net-tools (include netstat) are installed
which netstat

#install net-tools only in case not installed
sudo apt install net-tools

I install ufw (uncomplicated firewall) on my server and configure it to provide only SSH and HTTPS to the outside world.

# check if ufw is installed
ufw version
which ufw

#install ufw if not installed
sudo apt install ufw

#open SSH and HTTPS
sudo ufw allow OpenSSH
sudo ufw allow 443
sudo ufw allow 80/tcp

#Default rules
sudo ufw default deny incoming
sudo ufw default allow outgoing

#Start the firewall
sudo ufw enable

#Check the firewall status
sudo ufw status verbose
Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp (OpenSSH)           ALLOW IN    Anywhere                  
443                        ALLOW IN    Anywhere                  
80/tcp                     ALLOW IN    Anywhere                  
22/tcp (OpenSSH (v6))      ALLOW IN    Anywhere (v6)             
443 (v6)                   ALLOW IN    Anywhere (v6)             
80/tcp (v6)                ALLOW IN    Anywhere (v6)

Port 443 must run TCP and UDP

In the Docker environment, we will later configure Caddy as a reverse proxy for the vaultwarden service. Caddy requires both TCP and UDP on port 443. This is due to a modern protocol called HTTP/3 (QUIC).

Traditionally, the web (HTTP/1.1 and HTTP/2) ran exclusively over the TCP protocol. TCP is very reliable, but sometimes a bit slow when establishing a connection. Google and others subsequently developed QUIC, on which the new standard HTTP/3 is based. QUIC uses UDP instead of TCP.

HTTP/3 QUIC is significantly faster when establishing a connection (handshake). It handles packet loss better, which is especially important for mobile connections on smartphones, for example, when using the Bitwarden app.

Caddy is a very modern reverse proxy that has HTTP/3 enabled by default. The „normal“ HTTPS connection (HTTP/1.1 or HTTP/2) is established over TCP port 443. Caddy offers clients (Browsers or the Bitwarden app) the option to switch to HTTP/3 via UDP port 443.

With vaultwarden, users often access their vaults via smartphones using LTE or Wi-Fi connections. When UDP port 443 is open, the app uses HTTP/3. This results in a more stable connection and improved vault synchronization due to reduced latency.

Why must Port 80 be open

When you follow the instructions in the Article SSL Certificates with Lets Encrypt and certbot on a Linux Server then you are using certbot and install your LetsEncrypt certificates on your local server with the following certbot command :

sudo certbot certonly --standalone -d <yourDomain>

Here you use the method standalone. Whenever you renew your certificates certbot starts a temporary web server to prove ownership of your domain to LetsEncrypt.

When renewing your certificates certbot attempts to start a temporary web server on port 80. Therefore, port 80 must be open on your system via your firewall rules.

Important: If another web server (such as Nginx or Apache) is already running permanently on port 80, this step will fail unless the service is stopped. So, if a web server is running on port 80, this service must be permanently stopped.

After Certbot successfully starts the web server on port 80, the following happens:

• ACME Challenge: Certbot contacts the Let’s Encrypt servers. These provide Certbot with a random string (token).
• Deployment: Certbot creates a small file on the spot at the URL http://yourDomain/.well-known/acme-challenge/token
• Verification: The Let’s Encrypt servers now attempt to access this exact URL via the public internet. If they find the file (and the correct token), it proves that you own the server under this domain.
  

Once the verification is successful, the temporary standalone web server is immediately shut down and port 80 is opened. Certbot generates a new private key (if configured) and signs the new certificate. The new certificate files are stored in the directory /etc/letsencrypt/archive/ and the symbolic links in the directory /etc/letsencrypt/live/ are updated.

Create new user vaultwarden

You are logged in with your standarduser. From the home directory of the standarduser you create the user vaultwarden and create the hidden directory /home/vaultwarden/.ssh. Then copy the authorized_keys file from your .ssh directory into the new created .ssh directory of the new user vaultwarden and set the owner and permissions.

The new user vaultwarden should be in sudo group to perform commands under root using sudo. And the user vaultwarden should be in docker group to perform docker commands without using sudo.

#logged-in with standard user and create new user 
sudo adduser vaultwarden

#create hidden .ssh directory in new users home directory
sudo mkdir /home/vaultwarden/.ssh

#copy authorized_keys file to enable ssh key login for new user
cd /home/standarduser/.ssh
sudo cp authorized_keys /home/vaultwarden/.ssh

#set the owner vaultwarden and permissions
sudo chown -R vaultwarden:vaultwarden /home/vaultwarden/.ssh
sudo chmod 700 /home/vaultwarden/.ssh
sudo chmod 600 /home/vaultwarden/.ssh/authorized_keys

#check permissions
ls -al /home/vaultwarden
drwx-- vaultwarden vaultwarden 4096 May 11 14:20 .ssh

ls -l /home/vaultwarden/.ssh
-rw-- vaultwarden vaultwarden 400 May 11 14:20 authorized_keys

#add user vaultwarden to sudo- and docker group
sudo usermod -aG sudo vaultwarden
sudo usermod -aG docker vaultwarden

#check vaultwarden groups (3 groups: vaultwarden sudo docker)
sudo groups vaultwarden
vaultwarden : vaultwarden sudo docker

Create /opt/vaultwarden directory

Login with the new user vaultwarden. Stay logged in as vaultwarden for the next steps. Do not perform the next steps or the installation of the vaultwarden server with root or any other user.

After you are logged in with vaultwarden you create a new directory /opt/vaultwarden. This is the runtime directory of your vaultwarden application and the place from where the docker containers will be started.

sudo mkdir /opt/vaultwarden
sudo chmod -R 700 /opt/vaultwarden

ls -l /opt/vaultwarden
drwx--vaultwarden vaultwarden 4096 Mai 16 07:06 vaultwarden
 

Then change into /opt/vaultwarden. You create the /opt/vaultwarden/vw-data directory which is the host directory for the docker containers. One of these containers will be started under the container name vaultwarden. This container vaultwarden run with root privileges and write into this host directory /opt/vaultwarden/vw-data.

mkdir /opt/vaultwarden/vw-data

ls -l /opt/vaultwarden
drwxrwxr-x 6 vaultwarden vaultwarden 4096 Mai 15 15:54 vw-data
`

Create /opt/vaultwarden/certs and copy your SSL certificates

The container vaultwarden is the web application where you can log-in and manage your passwords. As we will se below the container will be started under the user vaultwarden in /opt/vaultwarden and run with root privileges behind a reverse proxy server. As reverse proxy I will use Caddy which is a powerful platform. Caddy manages the requests from the outside world and forward requests via an internal docker network to the vaultwarden server.

Caddy must accept only HTTPS connections and use the standard directory for certificates /opt/vaultwarden/certs. Therefore we create this directory.

I use Letsencrypt certificates which are managed automatically by certbot and stored in the directory /etc/letsencrypt on my host server. The keys are set up the following structure:

• In /etc/letsencrypt/live/<domain> there are only symlinks that point
• to the real files in /etc/letsencrypt/archive/<domain>.
  

Copy the fullchain.pem and privkey.pem files from /etc/letsencrypt/live/<domain> to /opt/vaultwarden/certs and set the permissions accordingly.

#create certs directory
mkdir /opt/vaultwarden/certs

#change into certs directory
cd /opt/vaultwarden/certs

#copy the files
cp /etc/letsencrypt/live/<domain>/fullchain.pem fullchain.pem
cp /etc/letsencrypt/live/<domain>/privkey.pem privkey.pem

#set owner and group vaultwarden
chown vaultwarden:vaultwarden fullchain.pem
chown vaultwarden:vaultwarden privkey.pem

#set access (read write only vaultwarden)
chmod 600 privkey.pem
chmod 600 fullchain.pem

note: The cp command will place the actual files (not the symlinks) into the directory /opt/vaultwarden/certs unless you specify a -P or -d option. So the cp command follows the symlinks and grab the actual files behind. This is important when the certificates have been renewed and new certificate files are stored behind the symlinks.

Run Vaultwarden and Caddy as docker containers

The following setup creates a secure, email-enabled Vaultwarden instance behind a Caddy reverse proxy with HTTPS and admin access, running entirely via Docker.

Create docker-compose.yml

This docker-compose.yml file sets up two services Vaultwarden and Caddy to host a self-hosted password manager with HTTPS support.

#docker-compose.yml

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: always
    environment:
      DOMAIN: "<yourDomain>"
      SIGNUPS_ALLOWED: "false"
      SMTP_HOST: "<yourSmtpServer>"
      SMTP_FROM: "<yourEmail>"
      SMTP_FROM_NAME: "<yourName>"
      SMTP_USERNAME: "<yourEmail>"
      SMTP_PASSWORD: "<yourSmtpPasswd>"
      SMTP_SECURITY: "force_tls"
      SMTP_PORT: "465"
      ADMIN_TOKEN: '<yourAdminToken>'
    volumes:
      - ./vw-data:/data

  caddy:
    image: caddy:2
    container_name: caddy
    restart: always
    ports:
      - 443:443
      - 443:443/udp 
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-config:/config
      - ./caddy-data:/data
      - ./certs:/certs:ro
    environment:
      DOMAIN: "<yourDomain>"
      LOG_FILE: "/data/access.log"

vaultwarden service:

Runs the Vaultwarden server (a lightweight Bitwarden-compatible backend).

• Disables user signups (SIGNUPS_ALLOWED: „false“).
• Configures SMTP settings for sending emails (e.g. for password resets).
• Sets a secure admin token (using Argon2 hash) to access the /admin interface.
• Persists Vaultwarden data to ./vw-data on the host.
  

Enable admin page access:

With the ADMIN_TOKEN set we enable login to the admin site via <yourDomain>/admin. First create a secure admin password. The <yourAdminToken> value can be created with your admin password piped into argon2. The result is a hash value that must be a little modified and then inserted as <yourAdminToken>. It is important that you use single quotes in docker-compose.yml when you insert <yourAdminToken>.

sudo apt install -y argon2
echo -n '<yourAdminPassword>' | argon2 somesalt -e

#This is the result of the argon2 hashing
$argon2i$v=19$m=4096,t=3,p=1$c29tZXNhbHQ$D...

Then you modify the hash by adding a $ sign in front of each $ sign in the hash. In this case we add 5 $ signs.

#original value
$argon2i$v=19$m=4096,t=3,p=1$c29thbHQ$D...

#modified value
$$argon2i$$v=19$$m=4096,t=3,p=1$$c29thbHQ$$D...

Then you put the modified value in single quotes into docker-compose.yml.

#docker-compose.yml

.....

ADMIN_TOKEN: '$$argon2i$$v=19$$m=4096,t=3,p=1$$c29thbHQ$$D...'

Now you can access the admin page with <yourDomain>/admin and login with your admin password.

caddy service:

Uses Caddy web server to reverse proxy to Vaultwarden.

• Handles HTTPS using custom certificates from ./certs.
• Binds to port 443 for secure access.
• Reads its configuration from ./Caddyfile.
• Logs access to /data/access.log (mapped from ./caddy-data on the host).
  

Create Caddyfile

Caddy is a modern, powerful web server that automatically handles HTTPS, reverse proxying, and more. Caddy acts as a secure HTTPS reverse proxy, forwarding external requests to the Vaultwarden Docker container running on internal port 80.

This Caddyfile defines how Caddy should serve and protect your vaultwarden instance over HTTPS.

#Caddyfile
https://<domain> {
  log {
    level INFO
    output file /data/access.log {
      roll_size 10MB
      roll_keep 10
    }
  }

  # Use custom certificate and key
  tls /certs/fullchain.pem /certs/privkey.pem

  # This setting may have compatibility issues with some browsers
  # (e.g., attachment downloading on Firefox). Try disabling this
  # if you encounter issues.
  encode zstd gzip

  # Admin path matcher
  @adminPath path /admin*
  
  # Basic Auth for admin access
  handle @adminPath {
    # If admin path require basic auth
    basicauth {
      superadmin <passwdhash>
    }

    reverse_proxy vaultwarden:80 {
      header_up X-Real-IP {remote_host}
    }
  }

  # Everything else
  reverse_proxy vaultwarden:80 {
    header_up X-Real-IP {remote_host}
  }
}

Domain

https://<domain>

This defines the domain name Caddy listens on (e.g. https://yourinstance.example.com).

Logging

log {
  level INFO
  output file /data/access.log {
    roll_size 10MB
    roll_keep 10
  }
}

Logs all access to a file inside the container (/data/access.log), with log rotation.

TLS with Custom Certificates

tls /certs/fullchain.pem /certs/privkey.pem

Use your own Let’s Encrypt certificates from mounted files rather than auto-generating them.

Compression

encode zstd gzip

Enables modern compression methods to improve performance, though may cause issues with attachments on some browsers.

Admin Area Protection

@adminPath path /admin*

Matches all requests to /admin paths.

handle @adminPath {
  basicauth {
    superadmin <passwdhash>
  }

  reverse_proxy vaultwarden:80 {
    header_up X-Real-IP {remote_host}
  }
}

• Requires HTTP Basic Auth for access to /admin.
• Proxies/Forwards authenticated admin requests to the Vaultwarden container.
• Ensures the backend sees the original client IP address.
  

All Other Requests

reverse_proxy vaultwarden:80 {
  header_up X-Real-IP {remote_host}
}

• Proxies/Forwards all non-/admin traffic directly to Vaultwarden container.
• Ensures the backend sees the original client IP address.
  

Protect your admin page

To protect your admin page we can use a HTTP Basic Auth. This mean whenever you access <yourDomain>/admin a login window will pop up in your browser and ask you to provide a user name and a password. We use htpasswd which is part of the apache2-utils.

#install apache2-utils if not available
sudo apt install apache2-utils

#Create a hash for the user admin (you can use any user-name) 
htpasswd -nB admin

New password: 
Re-type new password: 
admin:$2y$05$HZukVJWhWMrT7qMO2n65bm/5JYlt5tO...

Then you insert only the hash (without admin: ….) into the Caddyfile.

#Caddyfile

.....

handle @adminPath 
bash
  basicauth {
    admin $2y$05$HZukVJWhWMrT7qMO2n65bm/5JYlt5tO...
  }

Create ssl certificates with Letsencrypt and certbot

You can follow the instructions in my post on digitaldocblog.com. When you followed these instructions your ssl certificates are installed on your server in standalone mode. Whenever you renew your certificates certbot initiates the domain validation challenge and a temporary server will be started trying to listen on port 80. Because we run a web server this port is blocked and the web server must be stoped before we can initiate the renewal process.

To avoid this we should change the certbot renewal from standalone mode to webroot. Webroot is a method that leverages your existing web server to handle the domain validation challenge process without the need to stop the web server. Certbot places a temporary file with a unique token in a specific directory within your web servers public „webroot“ directory (e.g., /var/www/html/.well-known/acme-challenge/). Let’s Encrypt then sends a request to your domain to retrieve this file. Since your web server is already running, it can serve the file without any interruption to your website’s availability.

In our docker.compose.yml we defined the backend service vaultwarden. This service is the backend service listening to port 80. We also defined a web server service caddy listening to port 443.

In our Caddyfile we specified only a web server only for https://<Domain> working as a reverse proxy. Any request for https://<Domain> will be forwarded to the backend service vaultwarden listening on port 80 vaultwarden:80.

To enable webroot for certbot certificate renewal we must change the docker.compose.yml file. For the caddy service and in the ports section we must allow port 80 and expose a webroot directory via port 80 only for serving the domain challenge validation file. Therefore we create on the local host directory /opt/vaultwarden/caddyacme. In the volumes section of the caddy service we map this local directory 1:1 into the caddy container. Note: the notation with the dot like ./caddyacme:/caddyacme requires that the actual Caddyfile is in the same directory /opt/vaultwarden/Caddyfile than /opt/vaultwarden/caddyacme.

#docker-compose.yml

services:
  vaultwarden:
    image: vaultwarden/server:latest
    container_name: vaultwarden
    restart: always
    environment:
      DOMAIN: "https://bitwarden.rottlaender.eu"
      SIGNUPS_ALLOWED: "false"
      SMTP_HOST: "smtp.strato.de"
      SMTP_FROM: "bw@bitwarden.rottlaender.eu"
      SMTP_FROM_NAME: "Vaultwarden"
      SMTP_USERNAME: "bw@bitwarden.rottlaender.eu"
      SMTP_PASSWORD: "ZZqrmQEvydkxY3E2u8Y.KEbKNwgkTV"
      SMTP_SECURITY: "force_tls"
      SMTP_PORT: "465"
      ADMIN_TOKEN: '$$argon2i$$v=19$$m=4096,t=3,p=1$$c29tZXNhbHQ$$D/yu7vPhcpPz8Kk7G/R34YSO+NgtLzai0wVGSGL0RDE'
    volumes:
      - ./vw-data:/data

  caddy:
    image: caddy:2
    container_name: caddy
    restart: always
    ports:
      - 80:80
      - 80:80/udp
      - 443:443
      - 443:443/udp
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - ./caddy-config:/config
      - ./caddy-data:/data
      - ./certs:/certs:ro
      - ./caddy_acme:/caddy_acme
    environment:
      DOMAIN: "https://bitwarden.rottlaender.eu"
      LOG_FILE: "/data/access.log"

With this configuration we configure caddy to listen on port 80 and on port 443. In the current ufo firewall configuration we only allow the ports 22 and 443.

#Check the firewall status
sudo ufw status verbose

Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp (OpenSSH)           ALLOW IN    Anywhere                  
443                        ALLOW IN    Anywhere                  
22/tcp (OpenSSH (v6))      ALLOW IN    Anywhere (v6)             
443 (v6)                   ALLOW IN    Anywhere (v6)

We must open port 80 to enable the certbot webroot certificate renewal.

# open port 80
sudo ufw allow 80/tcp

# Check the firewall status
sudo ufw status verbose

Status: active
Logging: on (low)
Default: deny (incoming), allow (outgoing), deny (routed)
New profiles: skip

To                         Action      From
--                         ------      ----
22/tcp (OpenSSH)           ALLOW IN    Anywhere                  
443                        ALLOW IN    Anywhere                  
80/tcp                     ALLOW IN    Anywhere                  
22/tcp (OpenSSH (v6))      ALLOW IN    Anywhere (v6)             
443 (v6)                   ALLOW IN    Anywhere (v6)             
80/tcp (v6)                ALLOW IN    Anywhere (v6)

Then we must also change the Caddyfile. We must insert a http://.. block to enable caddy to serve the ACME challenge.

#Caddyfile

http://bitwarden.rottlaender.eu {
    # Serve ACME Challenge at Port 80
    handle_path /.well-known/acme-challenge/* {
        root * /caddy_acme
        file_server
    }

    # Any other request redirect to HTTPS
    @notACME not path /.well-known/acme-challenge/*
    handle @notACME {
        redir https://bitwarden.rottlaender.eu{uri} permanent
    }
}

https://bitwarden.rottlaender.eu {
  log {
    level INFO
    output file /data/access.log {
      roll_size 10MB
      roll_keep 10
    }
  }

  # Use custom certificate and key
  tls /certs/fullchain.pem /certs/privkey.pem

  # ACME Challenge for Certbot Webroot
  handle_path /.well-known/acme-challenge/* {
    root * /caddy_acme
    file_server
  }

  # This setting may have compatibility issues with some browsers (e.g., attachment downloading on Firefox). Try disabling this if you encounter issues.
  encode zstd gzip

  # Admin path matcher
  @adminPath path /admin*
  
  # Basic Auth for admin access
  handle @adminPath {
    # If admin path require basic auth
    basicauth {
      superadmin $2y$05$HZukVJWhWMrT7qMOIenLkuf2n65bm/6n260TPXKb4Wn825JYlt5tO  # Password Hash
    }

    reverse_proxy vaultwarden:80 {
      header_up X-Real-IP {remote_host}
    }
  }

  # Everything else
  reverse_proxy vaultwarden:80 {
    header_up X-Real-IP {remote_host}
  }
}

Then we must also change the /etc/letsencrypt/renewal/bitwarden.rottlaender.eu.conf to configure certbot to use webroot instead of standalone. Here change the authenticator directive to webroot and we add the webrootpath. Everything else keep the same.

# renew_before_expiry = 30 days
version = 1.21.0
archive_dir = /etc/letsencrypt/archive/bitwarden.rottlaender.eu
cert = /etc/letsencrypt/live/bitwarden.rottlaender.eu/cert.pem
privkey = /etc/letsencrypt/live/bitwarden.rottlaender.eu/privkey.pem
chain = /etc/letsencrypt/live/bitwarden.rottlaender.eu/chain.pem
fullchain = /etc/letsencrypt/live/bitwarden.rottlaender.eu/fullchain.pem

# Options used in the renewal process
[renewalparams]
account = 7844ed1ad487ff139e3adaa80aa7bbab
authenticator = webroot
webroot_path = /opt/vaultwarden/caddy_acme
server = https://acme-v02.api.letsencrypt.org/directory
renew_hook = /usr/local/bin/sync-certs.sh

And finally we must change the entry in the crontab. Before the depoly-hook we change the code to –webroot -w /opt/vaultwarden/caddyacme. This renewal will be executed daily at 03:30h. In case the certificates are still valid (no renewal required) then the deploy-hook will be skipped. Only in case a renewal must be executed the script /usr/local/bin/sync-certs.sh will be executed.

#crontab

30 3 * * * sh -c '/usr/bin/certbot renew --webroot -w /opt/vaultwarden/caddy_acme --deploy-hook /usr/local/bin/sync-certs.sh >> /var/log/certbot-renew.log 2>&1'

Create sync-certs.sh script and root crontab

This script copies renewed Let’s Encrypt certificates from the standard location to a custom destination /opt/vaultwarden/certs, sets strict permissions, assigns correct ownership, and restarts the Caddy container to apply the new certificates. At the end it reloads the Caddy container (via docker-compose restart) to apply new certs.

#!/bin/bash

# Variables
DOMAIN="<Domain>"
SRC="/etc/letsencrypt/live/$DOMAIN"
DEST="/opt/vaultwarden/certs"

# Check Source Directory
if [ ! -d "$SRC" ]; then
    echo "Certificate Path $SRC not found"
    exit 1
fi

# Check Destination Directory
if [ ! -d "$DEST" ]; then
    mkdir -p "$DEST"
    chown vaultwarden:vaultwarden "$DEST"
    chmod 700 "$DEST"
    echo "Target Path $DEST created"
fi

# Copy files (overwrite)
cp "$SRC/fullchain.pem" "$DEST/fullchain.pem"
cp "$SRC/privkey.pem" "$DEST/privkey.pem"

# set owner:group vaultwarden
chown vaultwarden:vaultwarden "$DEST/fullchain.pem"
chown vaultwarden:vaultwarden "$DEST/privkey.pem"

# set access (read write only vaultwarden)
chmod 600 "$DEST/privkey.pem"
chmod 600 "$DEST/fullchain.pem"

echo "[sync-certs] Certificates for $DOMAIN synced"

# successful sync of certificates – caddy re-start
echo "[sync-certs] re-start caddy ..."
cd /opt/vaultwarden
/usr/local/bin/docker-compose restart caddy

echo "[sync-certs] caddy reloaded new certificates"

Check Source Directory

if [ ! -d "$SRC" ]; then
    echo "Certificate Path $SRC not found"
    exit 1
fi

• What it checks: Whether the Let’s Encrypt certificate source directory for the domain exists.
• Why it’s needed:
  
  • Let’s Encrypt stores certificates as symlinks in /etc/letsencrypt/live/<domain>.
  • If this folder doesn’t exist, the script stops immediately to avoid copying from a missing or invalid source.
• Fail-safe: Prevents copying non-existent files, which would cause later commands to fail.
  

Check and Create Destination Directory

if [ ! -d "$DEST" ]; then
    mkdir -p "$DEST"
    chown vaultwarden:vaultwarden "$DEST"
    chmod 700 "$DEST"
    echo "Target Path $DEST created"
fi

• What it checks: Whether the destination directory for the copied certificates exists.
• If not:
  
  • It creates the directory (mkdir -p ensures parent paths are created if missing).
  • Sets secure permissions:
    
    • Owner: vaultwarden
    • Permissions: 700 – only the vaultwarden user can access the directory.
• Why this matters:
  
  • The vaultwarden container or process needs access to the certificates.
  • These permissions ensure only vaultwarden can read the certs, improving security.
    

Start, Stop and Check containers

Here are the most important docker-compose commands. Run these commands when you are in the directory where the docker-compose.yml file is and be sure that the logged in user is in the docker group (otherwise these commands work with sudo).

Here art the most important docker commands to check the status of containers.

Backup the vaultwarden data

To backup your database you must login to your remote server and navigate to the directory /opt/vaulwarden/vw-data.

cd /opt/vaultwarden/vw-data
ls -l /opt/vaultwarden/vw-data

drwxr-xr-x 2 root root    4096 Mai 14 07:29 attachments
-rw-r--r-- 1 root root 1437696 Mai 29 10:03 db_20250529_080308.sqlite3
-rw-r--r-- 1 root root 1437696 Mai 29 10:04 db_20250529_080448.sqlite3
-rw-r--r-- 1 root root 1445888 Aug  9 08:31 db_20250809_063113.sqlite3
-rw-r--r-- 1 root root 1552384 Aug 10 07:26 db.sqlite3
-rw-r--r-- 1 root root   32768 Sep  3 08:27 db.sqlite3-shm
-rw-r--r-- 1 root root  135992 Sep  3 08:27 db.sqlite3-wal
drwxr-xr-x 2 root root   16384 Sep  3 07:57 icon_cache
-rw-r--r-- 1 root root    1675 Mai 14 07:29 rsa_key.pem
drwxr-xr-x 2 root root    4096 Mai 14 07:29 sends
drwxr-xr-x 2 root root    4096 Mai 14 07:29 tmp

Before we run the backup here are some background infos.

Note: Pls. Be aware that you are currently navigating within your remote server not within the container vaultwarden. Under the service vaultwarden and volumes we defined in docker-compose.yml that the directory ./vw-data should be mounted into the container under the directory of /data. This mean that these directories are synchronized and you can check this by navigating within the container as follows.

To navigate within the container vaultwarden you can run the following commands.

#list your containers home directory
docker exec vaultwarden ls -l /

#list the data directory within your container
docker exec vaultwarden ls -l /data

With docker exec vaultwarden ls -l / you list your container root directory. Here you find among others the file vaultwarden which is basically the main program. With docker exec vaultwarden ls -l /data you list the files in /data on container side. You see exact the same files than in ./vw-data on your remote server.

All data of your vaultwarden service are stored in /data on container side. Here you have the database db.sqlite3 and various directories and other files.

To backup these data you run the program vaultwarden with the option backup.

#interactive mode
docker exec -it vaultwarden /vaultwarden backup

#standard mode
docker exec vaultwarden /vaultwarden backup
Backup to 'data/db_20250905_045937.sqlite3' was successful

The option exec -it is not necessary. It runs the command in interactive mode within the terminal.

This script:

1. Reads the database location and configurations on container side in /data.
2. Creates a backup of the SQLite database db.sqlite3, attachments, icons, etc.
3. Compresses everything as a .tar.gz archive.
4. Stores the archive in the /data directory on container side.
   

After executing this command the backup will be also be present in ./vw-data on your remote server.

Then you can download the backup from your remote server to your local computer. Note: Your local computer is in my case a Mac where I sit in front of and from where I connect to my remote server via ssh.

To download the backup you navigate on your local computer to the directory where you want to store your backup files. Then you run the scp command with the . at the end and download the backup files from your remote server into the current directory which should be your backup directory on your local computer.

#on your local computer
cd /Users/patrick/Software/docker/vaultwarden/backup

scp user@remote-host:/opt/vaultwarden/vw-data/<backupfile> .