Install and Deploy - Linux
This article will walk you through the procedure to install and deploy Bitwarden to your own Linux server. Bitwarden can also be installed and deployed on Windows machines. Please review Bitwarden software release support documentation.
x64, 2GHz dual core
Engine 19+ and Compose 1.24+
Engine 19+ and Compose 1.24+
The following is a summary of the installation procedure in this article. Links in this section will jump to detailed Installation procedure sections:
Configure your domain. Set DNS records for a domain name pointing to your machine, and open ports 80 and 443 on the machine.
Install Docker and Docker Compose on your machine.
Create a Bitwarden user & directory from which to complete installation.
Retrieve an installation id and key from https://bitwarden.com/host for use in installation.
For more information, see What are my installation id and installation key used for?
Install Bitwarden on your machine.
Configure your environment by adjusting settings in
At a minimum, configure the
globalSettings__mail__smtp...variables to setup an email server for inviting and verifying users.
Test your installation by opening your configured domain in a web browser.
By default, Bitwarden will be served through ports 80 (
http) and 443 (
https) on the host machine. Open these ports so that Bitwarden can be accessed from within and/or outside of the network. You may opt to choose different ports during installation.
We recommend configuring a domain name with DNS records that point to your host machine (for example,
bitwarden.example.com), especially if you are serving Bitwarden over the internet.
Bitwarden will be deployed and run on your machine using an array of Docker containers. Bitwarden can be run with any Docker edition or plan. Evaluate which edition is best for your installation.
Deployment of containers is orchestrated using Docker Compose. Some Docker installations, including Docker for macOS, come with Docker Compose already installed.
Install Docker and Docker Compose on your machine before proceeding with installation. Refer to the following Docker documentation for help:
Bitwarden is currently supported only in a Docker and Docker Compose environment. Bitwarden's installation scripts and manual installation artifacts do not accurately convert to Kubernetes manifests without extensive knowledge of the Bitwarden stack and Kubernetes. Automatic conversions of the installation artifacts are not recommended at this time and could result in a broken deployment environment.
We recommend configuring your Linux server with a dedicated
bitwarden service account, from which to install and run Bitwarden. Doing so will isolate your Bitwarden instance from other applications running on your server.
These steps are Bitwarden-recommended best practices, but are not required. For more information, see Docker's Post-installation steps for Linux documentation.
Create a bitwarden user:
sudo adduser bitwarden
Set password for bitwarden user (strong password):
sudo passwd bitwarden
Create a docker group (if it doesn’t already exist):
sudo groupadd docker
Add the bitwarden user to the docker group:
sudo usermod -aG docker bitwarden
Create a bitwarden directory:
sudo mkdir /opt/bitwarden
Set permissions for the
sudo chmod -R 700 /opt/bitwarden
Set the bitwarden user as owner of the
sudo chown -R bitwarden:bitwarden /opt/bitwarden
Bitwarden provides a shell script for easy installation on Linux and Windows (PowerShell). Complete the following steps to install Bitwarden using the shell script:
If you have created a Bitwarden user & directory, complete the following as the
bitwarden user from the
Download the Bitwarden installation script (
bitwarden.sh) to your machine:
curl -Lso bitwarden.sh "https://func.bitwarden.com/api/dl/?app=self-host&platform=linux" && chmod 700 bitwarden.sh
Run the installer script. A
./bwdatadirectory will be created relative to the location of
Complete the prompts in the installer:
Enter the domain name for your Bitwarden instance:
Typically, this value should be the configured DNS record.
Do you want to use Let's Encrypt to generate a free SSL certificate? (y/n):
yto generate a trusted SSL certificate using Let's Encrypt. You will be prompted to enter an email address for expiration reminders from Let's Encrypt. For more information, see Certificate Options.
nand use the Do you have a SSL certificate to use? option.
Enter your installation id:
Retrieve an installation id using a valid email at https://bitwarden.com/host. For more information, see what are my installation id and installation key used for?
Enter your installation key:
Retrieve an installation key using a valid email at https://bitwarden.com/host. For more information, see What are my installation id and installation key used for?
Do you have a SSL certificate to use? (y/n):
If you already have your own SSL certificate, specify
yand place the necessary files in the
./bwdata/ssl/your.domaindirectory. You will be asked whether it is a trusted SSL certificate (y/n). For more information, see Certificate Options.
nand use the self-signed SSL certificate? option, which is only recommended for testing purposes.
Do you want to generate a self-signed SSL certificate? (y/n):
yto have Bitwarden generate a self-signed certificate for you. This option is only recommended for testing. For more information, see Certificate Options.
If you specify
n, your instance will not use an SSL certificate and you will be required to front your installation with a HTTPS proxy, or else Bitwarden applications will not function properly.
Environment variables (required)
Some features of Bitwarden are not configured by the
bitwarden.sh script. Configure these settings by editing the environment file, located at
./bwdata/env/global.override.env. At a minimum, you should replace the values for:
... globalSettings__mail__smtp__host=<placeholder> globalSettings__mail__smtp__port=<placeholder> globalSettings__mail__smtp__ssl=<placeholder> globalSettings__mail__smtp__username=<placeholder> globalSettings__mail__smtp__password=<placeholder> ... adminSettings__admins= ...
globalSettings__mail__smtp...= placeholders to connect to the SMTP mail server that will be used to send verification emails to new users and invitations to organizations. Adding an email address to
adminSettings__admins= will provision access to the admin portal.
global.override.env, run the following command to apply your changes:
The Bitwarden installation script uses settings in
./bwdata/config.yml to generate the necessary assets for installation. Some installation scenarios (such as installations behind a proxy with alternate ports) may require adjustments to
config.yml that were not provided during standard installation.
config.yml as necessary and apply your changes by running:
Once you have completed all previous steps, start your Bitwarden instance:
The first time you start Bitwarden it may take some time as it downloads all of the images from Docker Hub.
Verify that all containers are running correctly:
Congratulations! Bitwarden is now up and running at
https://your.domain.com. Visit the web vault in your web browser to confirm that it's working.
You may now register a new account and log in. You will need to have configured
smtp environment variables (see Environment Variables) in order to verify the email for your new account.
If you are planning to self-host a Bitwarden organization, see self-host an organization to get started.
For additional information see self hosting FAQs.
The Bitwarden installation script (
bitwarden.ps1) has the following commands available:
PowerShell users will run the commands with a prefixed
- (switch). For example
Start the installer.
Start all containers.
Restart all containers (same as start).
Stop all containers.
Update all containers and the database.
Update/initialize the database.
Update this main script.
Update all containers without restarting the running instance.
Before this command executes, you will be prompted to save database files.
Rebuild generated installation assets from
List all commands.