Linux Manual Deployment
This article will walk you through the procedure to manually install and deploy Bitwarden to your own server. Please review Bitwarden software release support documentation.
warning
Manual installations should be conducted by advanced users only. Only proceed if you are very familiar with Docker technologies and desire more control over your Bitwarden installation.
Manual installations lack the ability to automatically update certain dependencies of the Bitwarden installation. As you upgrade from one version of Bitwarden to the next you will be responsible for changes to required environment variables, changes to nginx default.conf
, changes to docker-compose.yml
, and so on.
We will try to highlight these in the release notes on GitHub. You can also monitor changes to the dependency templates used by the Bitwarden installation script on GitHub.
Minimum | Recommended | |
---|---|---|
Processor | x64, 1.4GHz | x64, 2GHz dual core |
Memory | 2GB RAM | 4GB RAM |
Storage | 12GB | 25GB |
Docker Version | Engine 26+ and Compose | Engine 26+ and Compose |
ª
- Docker Compose is automatically installed as a plugin when you download Docker Engine. Download Docker Engine for Linux.
Additionally, if you're building your own Bitwarden images, official .NET Core Runtime images (download from DockerHub) of the same .NET version as Bitwarden are required. You must use the Debian or Ubuntu versions.
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:
Bashsudo adduser bitwarden
Set a password for the bitwarden user:
Bashsudo passwd bitwarden
Create a docker group (if it doesn't already exist):
Bashsudo groupadd docker
Add the bitwarden user to the docker group:
Bashsudo usermod -aG docker bitwarden
Create a bitwarden directory:
Bashsudo mkdir /opt/bitwarden
Set permissions for the
/opt/bitwarden
directory:Bashsudo chmod -R 700 /opt/bitwarden
Set the bitwarden user ownership of the
/opt/bitwarden
directory:Bashsudo chown -R bitwarden:bitwarden /opt/bitwarden
warning
If you have created a Bitwarden user & directory, complete the following as the bitwarden
user from the /opt/bitwarden
directory. Do not install Bitwarden as root, as you will encounter issues during installation.
To download Bitwarden and configure Bitwarden server assets:
Download a stubbed version of Bitwarden's dependencies (
docker-stub-US.zip
ordocker-stub-EU.zip
) from the releases pages on GitHub. For example:Bashcurl -L https://github.com/bitwarden/server/releases/download/v<version_number>/docker-stub-US.zip \ -o docker-stub-US.zip
Create a new directory named
bwdata
and extractdocker-stub.zip
to it, for example:Bashunzip docker-stub-US.zip -d bwdata
Once unzipped, the
bwdata
directory will match what thedocker-compose.yml
file's volume mapping expects. You may, if you wish, change the location of these mappings on the host machine.In
./bwdata/env/global.override.env
, edit the following environment variables:globalSettings__baseServiceUri__vault=
: Enter the domain of your Bitwarden instance.globalSettings__sqlServer__ConnectionString=
: Replace theRANDOM_DATABASE_PASSWORD
with a secure password for use in a later step.globalSettings__identityServer__certificatePassword
: Set a secure certificate password for use in a later step.globalSettings__internalIdentityKey=
: ReplaceRANDOM_IDENTITY_KEY
with a random alphanumeric string.globalSettings__oidcIdentityClientKey=
: ReplaceRANDOM_IDENTITY_KEY
with a random alphanumeric string.globalSettings__duo__aKey=
: ReplaceRANDOM_DUO_AKEY
with a random alphanumeric 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.tip
At this time, consider also setting values for all
globalSettings__mail__smtp__
variables and foradminSettings__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.
From
./bwdata
, generate a.pfx
certificate file for the identity container and move it to the mapped volume directory (by default,./bwdata/identity/
). For example, run the following commands:Bashopenssl req -x509 -newkey rsa:4096 -sha256 -nodes -keyout identity.key -out identity.crt -subj "/CN=Bitwarden IdentityServer" -days 10950
and
Bashopenssl pkcs12 -export -out ./identity/identity.pfx -inkey identity.key -in identity.crt -passout pass:IDENTITY_CERT_PASSWORD
In the above command, replace
IDENTITY_CERT_PASSWORD
with the certificate password created and used in Step 3.Create a subdirectory in
./bwdata/ssl
named for your domain, for example:Bashmkdir ./ssl/bitwarden.example.com
Provide a trusted SSL certificate and private key in the newly created
./bwdata/ssl/bitwarden.example.com
subdirectory.note
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.In
./bwdata/nginx/default.conf
:Replace all instances of
bitwarden.example.com
with your domain, including in theContent-Security-Policy
header.Set the
ssl_certificate
andssl_certificate_key
variables to the paths of the certificate and private key provided in Step 7.Take one of the following actions, depending on your certificate setup:
If using a trusted SSL certificate, set the
ssl_trusted_certificate
variable to the path to your certificate.If using a self-signed certificate, comment out the
ssl_trusted_certificate
variable.
In
./bwdata/env/mssql.override.env
, replaceRANDOM_DATABASE_PASSWORD
with the password created in Step 3.In
./bwdata/web/app-id.json
, replacebitwarden.example.com
with your domain.In
./bwdata/env/uid.env
, set the UID and GID of thebitwarden
users and group you created earlier so the containers run under them, for example:BashLOCAL_UID=1001 LOCAL_GID=1001
Start your Bitwarden server with the following command:
Bashdocker compose -f ./docker/docker-compose.yml up -d
Verify that all containers are running correctly:
Bashdocker ps
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. You will need to have configured SMPT 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.
Updating a self-hosted server that has been installed and deployed manually is different from the standard update procedure. To update your manually-installed server:
Download the latest
docker-stub.zip
archive from the releases pages on GitHub.Unzip the new
docker-stub.zip
archive and compare its contents with what's currently in yourbwdata
directory, copying anything new to the pre-existing files inbwdata
.
Do not overwrite your pre-existingbwdata
directory with the contents of the newerdocker-stub.zip
archive, as this would overwrite any custom configuration work you've done.Run the following command to restart your server with your updated configuration and the latest containers:
Bashdocker compose -f ./docker/docker-compose.yml down && docker compose -f ./docker/docker-compose.yml up -d
Suggest changes to this page
How can we improve this page for you?
For technical, billing, and product questions, please contact support