Knowledgebase

Introduction

Vaultwarden is an unofficial Bitwarden server alternative written in Rust. It uses supports connections via Bitwarden clients and is less resource-heavy than the official Bitwarden service. This tutorial explains how to install Vaultwarden on Ubuntu 20.04 with Docker and docker-compose, and uses Caddy to secure the configuration.

Prerequisites

Before you begin these steps, you should:

• Deploy an Ubuntu 20.04 server.
• Update the server.
• Create a non-root user with sudo privileges.
• Log in to your server as a non-root user.
• Open port 433 on your RCS firewall or your ufw.

You should also create a DNS "A" record that points a hostname to the IP address of your server. Caddy requires a DNS name to install a TLS/SSL certificate.

Installation

1. Remove any older versions of Docker and the Docker engine.

   $ sudo apt remove docker docker.io containerd runc
   

2. Ensure that your version of snapd is up to date.

   $ sudo snap install core; sudo snap refresh core
   

3. Install Docker using snap.

   $ sudo snap install docker
   

Configuration

Docker Container

1. Create a directory called vaultwarden in your home directory and enter it.

   $ mkdir ~/vaultwarden
   $ cd ~/vaultwarden
   

2. Create and open a new docker-compose.yml file.

   $ nano docker-compose.yml
   

3. Add the following lines to the file.

   version: '3'
   
   services:
     vaultwarden:
       image: vaultwarden/server:latest
       container_name: vaultwarden
       restart: always
       environment:
         - WEBSOCKET_ENABLED=true
       volumes:
         - ./vw-data:/data
   
     caddy:
       image: caddy:2
       container_name: caddy
       restart: always
       ports:
         - 80:80
         - 443:443
       volumes:
         - ./Caddyfile:/etc/caddy/Caddyfile:ro
         - ./caddy-config:/config
         - ./caddy-data:/data
       environment:
         - DOMAIN=
         - EMAIL=
         - LOG_FILE=/data/access.log
   

4. Add the domain name or subdomain to the DOMAIN value under Caddy's environment variables.

   environment:
     - DOMAIN=https://example.com
   

5. Add an email address for TLS/SSL certificate registration to the EMAIL value under Caddy's environment variables.

   environment:
     - DOMAIN=https://example.com
     - EMAIL=user@example.com
   

6. Save and exit the text editor by using CTRL + X, then Y, followed by ENTER.

Caddy Configuration File

1. Create and open a new Caddyfile.

   $ nano Caddyfile
   

2. Add the following lines to the file.

   {$DOMAIN}:443 {
     log {
       level INFO
       output file {$LOG_FILE} {
         roll_size 10MB
         roll_keep 10
       }
     }
   
     # Get a cert by using the ACME HTTP-01 challenge.
     tls {$EMAIL}
   
     encode gzip
   
     # Headers to improve security.
     header {
     # Enable HSTS
     Strict-Transport-Security "max-age=31536000;"
   
     # Enable cross-site filter (XSS)
     X-XSS-Protection "1; mode=block"
   
     # Disallow the site to be rendered within a frame (clickjacking protection)
     X-Frame-Options "DENY"
   
     # Prevent search engines from indexing
     X-Robots-Tag "none"
   
     # Remove Caddy branding
     -Server
     }
   
     # Redirect notifications to the WebSocket.
     reverse_proxy /notifications/hub vaultwarden:3012
   
     reverse_proxy vaultwarden:80 {
          header_up X-Real-IP {remote_host}
     }
   }
   

3. Save and exit the text editor by using CTRL + X, then Y, followed by ENTER.

The Caddyfile configures Caddy to forward HTTPS requests from port 443 to Vaultwarden and adds additional headers to improve security, such as HTTP Strict Transport Security (HSTS) and Cross-Site Scripting (XSS) protection.

Running Vaultwarden

1. Run Vaultwarden by using docker-compose in detached mode. This may take a few seconds.

   $ sudo docker-compose up -d
   

2. Check that Vaultwarden is running by using docker. The status should be Up.

   $ sudo docker ps
   STATUS
   Up x seconds/minutes
   

Additional Security Configuration

To further improve security, additional configuration is available.

Disabling Registration

By default, anyone who accesses your Vaultwarden instance can create an account. This is useful when first creating your instance but may pose a security risk later.

After creating your account, you can disable registration by setting the SIGNUPS_ALLOWED environment variable to false in docker-compose.yml.

services:
  vaultwarden:
    ... other configuration ...
    environment:
      - SIGNUPS_ALLOWED=false
      ... other configuration ...

Disabling Invitations

Vaultwarden also allows registered users to invite other new users to create accounts on the server. This feature is not a security risk as long as you trust your users. However, if you are the only user, you may want to disable this.

You can disable invitations by setting the INVITATIONS_ALLOWED environment variable to false in docker-compose.yml.

services:
  vaultwarden:
    ... other configuration ...
    environment:
      - INVITATIONS_ALLOWED=false
      ... other configuration ...

Disabling Password Hints

Bitwarden's password hints are usually sent by email. However, Vaultwarden accommodates personal deployments, so password hints are available on the password hint page. This feature exists, so you do not have to configure an email service.

If you want to disable password hints, set the SHOW_PASSWORD_HINT variable to false in docker-compose.yml.

services:
  vaultwarden:
    ... other configuration ...
    environment:
      - SHOW_PASSWORD_HINT=false
      ... other configuration ...

Finishing Steps

Saving Your New Configuration

If you changed any of the environment variables from the steps above, you must restart Vaultwarden. To do this, follow these steps:

1. Stop Vaultwarden by using docker-compose.

   $ sudo docker-compose down
   

2. Rerun Vaultwarden by using docker-compose in detached mode.

   $ sudo docker-compose up -d
   

Your new configuration should now be in effect.

Use Bitwarden to Access Your Vaultwarden Instance

You can use upstream Bitwarden clients by changing the server URL to your Vaultwarden instance.

Using Vaultwarden

You should now navigate to your Vaultwarden installation and create an account (if you haven't already).

https://example.com

After logging in, you can start adding your logins and passwords to your vault.

This completes the steps to install Vaultwarden and secure it using Caddy.

More Information

• Vaultwarden Documentation
• Vaultwarden GitHub Repository
• Caddy Documentation
• Bitwarden Website