Install and Deploy - Offline
This article will walk you through the procedure to install and deploy Bitwarden to your own server in an offline or air-gapped environment.
Before proceeding with the installation, please ensure the following requirements are met:
Using a machine with internet access, you have downloaded the latest
docker-stub.zipfile from the Bitwarden Server repository's releases page and transferred this file to your server.
An offline SMTP Server is setup and active in your environment.
|Processor||x64, 1.4GHz||x64, 2GHz dual core|
|Memory||2GB RAM||4GB RAM|
|Docker Version||Engine 19+ and Compose 1.24+||Engine 19+ and Compose 1.24+|
Create Bitwarden Local User & Directory
We recommend configuring your 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 a password for the bitwarden user:
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 ownership of the
sudo chown -R bitwarden:bitwarden /opt/bitwarden
Configure your Machine
To configure your machine with the assets required for your Bitwarden server:
If you've created a Bitwarden User & Directory, complete the following as the
bitwarden user from the
Create a new directory named
docker-stub.zipto it, for example:
unzip docker-stub.zip -d bwdata
Once unzipped, the
bwdatadirectory will match what the
docker-compose.ymlfile's volume mapping expects. You may, if you wish, change the location of these mappings on the host machine.
./bwdata/env/global.override/env, edit the following environment variables:
globalSettings__baseServiceUri__vault=: Enter the domain of your Bitwarden instance.
globalSettings__sqlServer__ConnectionString=: Replace the
RANDOM_DATABASE_PASSWORDwith a secure password for use in a later step.
globalSettings__identityServer__certificatePassword: Set a secure certificate password for use in a later step.
RANDOM_IDENTITY_KEYwith a random key string.
RANDOM_IDENTITY_KEYwith a random key string.
RANDOM_DUO_AKEYwith a random key string.
globalSettings__installation__id=: Enter an installation id retrieved from https://bitwarden.com/host.
globalSettings__installation__key=: Enter an installation key retrieved from https://bitwarden.com/host.
At this time, consider also setting values for all
globalSettings__mail__smtp__variables and for
adminSettings__admins. Doing so will configure the SMTP mail server used to send invitations to new Organization members and provision access to the System Administrator Portal.
./bwdata, generate a
.pfxcertificate file for the identity container and move it to the mapped volume directory (by default,
./bwdata/identity/). For example, run the following commands:
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout identity.key -out identity.crt -subj "/CN=Bitwarden IdentityServer" -days 10950
openssl pkcs12 -export -out ./identity/identity.pfx -inkey identity.key -in identity.crt -passout pass:IDENTITY_CERT_PASSWORD
In the above command, replace
IDENTITY_CERT_PASSWORDwith the certificate password created and used in Step 2.
Create a subdirectory in
./bwdata/sslnamed for your domain, for example:
Provide a trusted SSL certificate and private key in the newly created
This directory is mapped to the NGINX container at
/etc/ssl. If you can't provide a trusted SSL certificate, front the installation with a proxy that provides an HTTPS endpoint to Bitwarden client applications.
Replace all instances of
bitwarden.example.comwith your domain, including in the
ssl_certificate_keyvariables to the paths of the certificate and private key provided in Step 6.
Take one of the following actions, depending on your certificate setup:
If using a trusted SSL certificate, set the
ssl_trusted_certificatevariable to the path to your certificate.
If using a self-signed certificate, comment out the
RANDOM_DATABASE_PASSWORDwith the password created in Step 2.
bitwarden.example.comwith your domain.
./bwdata/env/uid.env, set the UID and GID of the
bitwardenusers and group you created earlier so the containers run under them, for example:
Download & Transfer Images
To get docker images for use on your offline machine:
From an internet-connected machine, download all
bitwarden/xxx:latestdocker images, as listed in the
Save each image to a
.imgfile, for example:
docker image save -o mssql.img bitwarden/mssql:version
.imgfiles to your offline machine.
On your offline machine, load each
.imgfile to create your local docker images, for example:
docker image load mssql.img
Start your Server
Start your Bitwarden server with the following command:
docker-compose -f ./docker/docker-compose.yml up -d
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 browser to confirm that it's working.
You may now register a new account and log in. Your will need to have configured SMPT environment variables (see Environment Variables) in order to verify the email for your new account.