Complete Guide to Installing and Self-Hosting Bitwarden on Ubuntu 20.04+ with Docker

Self-hosting your password manager gives you complete control over your sensitive credentials. This comprehensive guide walks you through setting up Bitwarden on Ubuntu using Docker, with security best practices, troubleshooting tips, and maintenance procedures to ensure a robust deployment.

Introduction: Why Self-Host Bitwarden?#

Bitwarden is an open-source password manager that securely stores your sensitive information in an encrypted vault. Self-hosting Bitwarden provides several key advantages:

• Complete control over your password data
• No reliance on third-party servers for storing sensitive information
• Enhanced privacy since you manage where your data resides
• Customizable configuration based on your specific needs

Using Docker for deployment simplifies the installation and maintenance processes by containerizing the application and its dependencies, making the entire setup more portable and easier to manage.

instruction layout

Prerequisites#

Before beginning the installation, ensure your system meets the following requirements:

• Ubuntu 20.04 LTS or newer (this guide works for Ubuntu 22.04 as well)
• A server with at least 2GB of RAM
• Minimum 10GB free disk space
• Internet connection for downloading packages
• Root or sudo privileges
• A domain name pointing to your server (for secure access)
• Open ports 80 and 443 on your firewall

System Preparation#

First, update your system to ensure you have the latest packages:

sudo apt update && sudo apt upgrade -y

This step minimizes compatibility issues and security vulnerabilities by bringing your system up to date.

Next, install the necessary dependencies for Docker installation:

sudo apt install apt-transport-https ca-certificates curl gnupg-agent software-properties-common -y

These packages enable secure APT repositories, certificate verification, and other requirements for Docker.

If any package fails to install, you might see error messages. In that case, try running the update command again to fix any potential repository issues.

Creating a Dedicated Bitwarden User#

For security reasons, it's best to create a dedicated user for running Bitwarden. This isolates the Bitwarden installation from other applications and follows the principle of least privilege.

Create a directory for Bitwarden:

sudo mkdir -p /opt/bitwarden

Create a dedicated user named 'bitwarden' with the home directory at /opt/bitwarden:

sudo useradd -s /bin/bash -d /opt/bitwarden bitwarden

Set proper directory permissions:

sudo chmod -R 700 /opt/bitwarden
sudo chown -R bitwarden:bitwarden /opt/bitwarden

These permissions ensure that only the bitwarden user can access the installation directory.

Installing Docker and Docker Compose#

Docker is required to run Bitwarden containers. Let's add the official Docker repository and install Docker.

Add Docker's official GPG key:

curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

Add the Docker repository:

echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

Update package information:

sudo apt update

Install Docker:

sudo apt install docker-ce docker-ce-cli containerd.io -y

Verify Docker installation:

sudo systemctl status docker

You should see "active (running)" in the output. If Docker isn't running, start it with:

sudo systemctl start docker && sudo systemctl enable docker

This command both starts Docker and ensures it launches automatically on system boot.

Allow the bitwarden user to run Docker commands:

sudo usermod -aG docker bitwarden

Adding the bitwarden user to the docker group allows it to execute Docker commands without sudo.

Installing Bitwarden#

Now we're ready to install Bitwarden. Switch to the bitwarden user and navigate to its home directory:

sudo su - bitwarden
cd /opt/bitwarden

Download the official Bitwarden installation script:

curl -Lso bitwarden.sh https://go.btwrdn.co/bw-sh

Make the script executable:

chmod +x bitwarden.sh

Before running the installation, you need to obtain a Bitwarden installation ID and key from Bitwarden's website. Visit https://bitwarden.com/host/ and complete the form to receive your installation ID and key by email.

Run the installation script:

./bitwarden.sh install

The installation wizard will prompt you for several pieces of information:

1. Your domain name (e.g., bitwarden.yourdomain.com)
2. Whether to use Let's Encrypt for SSL (recommended for production)
3. Your email address (for Let's Encrypt certificates)
4. Your installation ID
5. Your installation key

If any prompt fails to appear or the installation stops unexpectedly, check for error messages in the terminal output. Common issues include network connectivity problems or insufficient disk space.

Starting Bitwarden Server#

After installation completes, start the Bitwarden server:

./bitwarden.sh start

Verify all containers are running:

docker ps

You should see multiple Bitwarden containers running. If any container is missing or shows a status other than "Up", check the logs:

docker logs bitwarden-mssql

Replace "bitwarden-mssql" with the name of the problematic container.

Configuring SMTP for Email#

Email functionality is important for account recovery and notifications. Edit the global environment file:

nano /opt/bitwarden/bwdata/env/global.override.env

Configure the email settings by adding or modifying these lines:

[email protected]
globalSettings__mail__smtp__host=smtp.your-provider.com
globalSettings__mail__smtp__port=587
globalSettings__mail__smtp__ssl=true
[email protected]
globalSettings__mail__smtp__password=your_password
globalSettings__mail__smtp__useDefaultCredentials=false

After modifying the configuration, restart Bitwarden:

./bitwarden.sh restart

If email sending fails, check your SMTP settings and ensure your email provider allows SMTP access from your server's IP address.

Security Considerations#

Securing your Bitwarden instance is crucial since it contains sensitive information. Here are essential security measures:

Restrict Admin Access#

Edit the global environment file:

nano /opt/bitwarden/bwdata/env/global.override.env

Add the following line to disable new user registrations (recommended for personal or small team use):

globalSettings__disableUserRegistration=true

Restart Bitwarden to apply changes:

./bitwarden.sh restart

Set Up Proper Firewall Rules#

Install and configure UFW (Uncomplicated Firewall):

sudo apt install ufw -y
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow ssh
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Verify the firewall status:

sudo ufw status

If your SSH port is not the default (22), replace "ssh" with your specific port.

Regular Updates#

Keep your Bitwarden installation updated:

./bitwarden.sh updateself
./bitwarden.sh update

These commands update both the installation script itself and the Bitwarden application.

Backup and Restoration#

Regular backups are essential for data safety. Bitwarden automatically takes nightly backups of the database, but a comprehensive backup strategy includes more elements.

Setting Up Manual Backups#

Create a backup script:

nano /opt/bitwarden/backup.sh

Add the following content:

#!/bin/bash
# Create timestamp
TIMESTAMP=$(date +"%Y%m%d_%H%M%S")
BACKUP_DIR="/opt/bitwarden/backups/$TIMESTAMP"

# Create backup directory
mkdir -p $BACKUP_DIR

# Stop Bitwarden to ensure data consistency
/opt/bitwarden/bitwarden.sh stop

# Backup important directories
cp -r /opt/bitwarden/bwdata/env $BACKUP_DIR/
cp -r /opt/bitwarden/bwdata/core/attachments $BACKUP_DIR/
cp -r /opt/bitwarden/bwdata/mssql/data $BACKUP_DIR/
cp -r /opt/bitwarden/bwdata/core/aspnet-dataprotection $BACKUP_DIR/
cp -r /opt/bitwarden/bwdata/ssl $BACKUP_DIR/

# Restart Bitwarden
/opt/bitwarden/bitwarden.sh start

# Compress backup
tar -czf /opt/bitwarden/backups/bitwarden_backup_$TIMESTAMP.tar.gz -C /opt/bitwarden/backups $TIMESTAMP

# Remove uncompressed backup directory
rm -rf $BACKUP_DIR

echo "Backup completed: /opt/bitwarden/backups/bitwarden_backup_$TIMESTAMP.tar.gz"

Make the script executable:

chmod +x /opt/bitwarden/backup.sh

Create a backup directory:

mkdir -p /opt/bitwarden/backups

To run a manual backup:

/opt/bitwarden/backup.sh

For automated backups, set up a cron job. Open the crontab:

crontab -e

Add this line to run the backup weekly at 2 AM on Sunday:

0 2 * * 0 /opt/bitwarden/backup.sh

Restoring from Backup#

To restore from backup:

# Extract backup
tar -xzf /opt/bitwarden/backups/bitwarden_backup_TIMESTAMP.tar.gz -C /opt/bitwarden/backups/

# Stop Bitwarden
/opt/bitwarden/bitwarden.sh stop

# Restore directories
cp -r /opt/bitwarden/backups/TIMESTAMP/env /opt/bitwarden/bwdata/
cp -r /opt/bitwarden/backups/TIMESTAMP/attachments /opt/bitwarden/bwdata/core/
cp -r /opt/bitwarden/backups/TIMESTAMP/data /opt/bitwarden/bwdata/mssql/
cp -r /opt/bitwarden/backups/TIMESTAMP/aspnet-dataprotection /opt/bitwarden/bwdata/core/
cp -r /opt/bitwarden/backups/TIMESTAMP/ssl /opt/bitwarden/bwdata/

# Fix permissions
chown -R bitwarden:bitwarden /opt/bitwarden/bwdata

# Start Bitwarden
/opt/bitwarden/bitwarden.sh start

Replace "TIMESTAMP" with your actual backup timestamp.

Common Problems and Solutions#

Here are some common issues users encounter and their solutions:

Container Startup Failures#

If containers fail to start:

# Check container status
docker ps -a

# View logs of specific container
docker logs bitwarden-mssql

Solution: If the error relates to permissions, ensure proper ownership:

sudo chown -R bitwarden:bitwarden /opt/bitwarden/bwdata

Database Connection Issues#

If you experience database connectivity problems:

# Check database container is running
docker ps | grep mssql

# View database logs
docker logs bitwarden-mssql

Solution: You may need to recreate the database container:

./bitwarden.sh rebuild mssql

SSL Certificate Problems#

If SSL certificates aren't working properly:

# Check certificate status
ls -la /opt/bitwarden/bwdata/ssl

Solution: Reinstall certificates:

./bitwarden.sh updateself
./bitwarden.sh update
./bitwarden.sh rebuild nginx

Email Configuration Issues#

If email notifications aren't working:

# Check mail settings
grep -A 10 "mail" /opt/bitwarden/bwdata/env/global.override.env

Solution: Verify your SMTP settings and test with a simple telnet command:

telnet your-smtp-server 587

If telnet isn't installed:

sudo apt install telnet -y

"Read-only File System" Error#

Some users encounter "mkdir /bw-data: read-only file system" errors:

# Check filesystem status
df -h

# Check for errors
dmesg | grep -i error

Solution: This often indicates filesystem corruption. Try remounting the filesystem:

sudo mount -o remount,rw /

If the issue persists, consider changing the data path in your Docker configuration.

Maintenance Tasks#

Regular maintenance ensures your Bitwarden instance remains secure and performs optimally.

Updating Bitwarden#

Update the Bitwarden installation script:

./bitwarden.sh updateself

Update Bitwarden:

./bitwarden.sh update

Rebuild and restart:

./bitwarden.sh rebuild
./bitwarden.sh restart

Monitoring Disk Space#

Monitor disk space regularly:

df -h

If space is running low, clean Docker:

docker system prune -a --volumes

This command removes unused containers, networks, images, and volumes. Be careful, as it can delete useful data.

Log Rotation#

Set up log rotation to prevent logs from consuming excessive disk space:

sudo nano /etc/logrotate.d/bitwarden

Add the following:

/opt/bitwarden/bwdata/logs/*.log {
    daily
    missingok
    rotate 14
    compress
    delaycompress
    notifempty
    create 0640 bitwarden bitwarden
}

Known Issues and Workarounds#

Memory Usage with MSSQL#

The MSSQL container can use significant memory, which might be problematic on smaller servers.

Workaround: Adjust MSSQL memory settings:

nano /opt/bitwarden/bwdata/env/mssql.override.env

Add:

MSSQL_MEMORY_LIMIT_MB=1024

Restart:

./bitwarden.sh restart

Web Vault Connectivity Issues#

Users sometimes encounter "Error fetching network" messages when accessing the web vault.

Workaround: Clear browser cache or try a different browser. If that doesn't help, rebuild the web container:

./bitwarden.sh rebuild web

Database Corruption#

In rare cases, the database may become corrupted.

Workaround: Restore from the latest automatic backup:

# Stop Bitwarden
./bitwarden.sh stop

# Find the latest backup
ls -la /opt/bitwarden/bwdata/mssql/backups

# Restore database (replace DATE with actual date)
cp /opt/bitwarden/bwdata/mssql/backups/vault_DATE.bak /opt/bitwarden/bwdata/mssql/data/

# Start Bitwarden
./bitwarden.sh start

Conclusion#

You now have a secured and properly configured Bitwarden installation on your Ubuntu server. This setup provides a robust, self-hosted password management solution that gives you complete control over your sensitive data. Regular maintenance and backups will ensure your installation remains secure and reliable.

Remember that while self-hosting provides increased privacy and control, it also means you're responsible for security, backups, and maintenance. Following the steps in this guide will help you manage these responsibilities effectively.

For additional support, visit the official Bitwarden community forums or GitHub repository, where many users share their experiences and solutions to common problems.