mirror of
https://github.com/bitwarden/help
synced 2025-12-06 00:03:30 +00:00
Self-host edits & adds (#323)
* Self-host Initial Refresh * typo fixes * add system boot config * typo fix * installation edits * backup - add offline backup * typo fix
This commit is contained in:
fred_the_tech_writer
committed by
GitHub
GitHub
parent
e544015381
commit
556fcaaea6
@@ -6,213 +6,110 @@ featured: true
|
||||
popular: true
|
||||
hidden: false
|
||||
tags: []
|
||||
order: 11
|
||||
---
|
||||
|
||||
## Bitwarden Server service/user account and optional systemd service configuration)
|
||||
This article contains Frequently Asked Questions (FAQs) regarding **Self-hosting**.
|
||||
|
||||
{% callout info %}
|
||||
You will want to configure the Bitwarden Server to use a `bitwarden` service account. $USER=bitwarden You will want to have your installation owned by the bitwarden service account, and you should be logged in as bitwarden.
|
||||
## General
|
||||
|
||||
After those are verified, you will want to make sure the UID and GID in the /bwdata/env/uid.env file are set to your bitwarden service account id numbers in Linux. When using the bitwarden service account you will also need to follow these steps:
|
||||
#### Q: What platforms can I host on?
|
||||
|
||||
1. Make sure the docker group has been created. sudo groupadd docker
|
||||
2. Add the bitwarden account to the docker group sudo usermod -aG docker $USER
|
||||
3. Create the bitwarden service file (may want to store it with your bitwarden installation) sudo vi bitwarden.service [Unit] Description=Bitwarden Requires=docker.service After=docker.service [Service] Type=oneshot User=bitwarden Group=bitwarden ExecStart={INSTALL_DIR}/bitwarden.sh start RemainAfterExit=true ExecStop= {INSTALL_DIR}/bitwarden.sh stop [Install] WantedBy=multi-user.target
|
||||
4. Copy the bitwarden service file to systemd. sudo cp bitwarden.service /etc/systemd/system/bitwarden.service
|
||||
5. Set permissions on bitwarden service file under systemd. sudo chmod 644 /etc/systemd/system/bitwarden.service
|
||||
6. Optional (reload for testing) systemctl daemon-reload
|
||||
7. Add service to start with system boot. sudo systemctl enable bitwarden.service
|
||||
{% endcallout %}
|
||||
**A:** Bitwarden is a cross-platform application that is deployed using Docker Linux containers. This means that Bitwarden can be hosted on Linux, macOS, and Windows machines.
|
||||
|
||||
### Certificate Setup for Private CA, on-premises or self-hosted
|
||||
You can read more about Docker and container technologies at [Docker's Website](https://www.docker.com/why-docker){:target="_blank"}.
|
||||
|
||||
When configuring your server you will need to have three files, private key, server cert, and the CA cert then you will configure their path in the config.yml file in the Bitwarden installation directory.
|
||||
#### Q: How should I achieve High Availability?
|
||||
|
||||
The path that is defined in the `config.yml` is actually the location inside the NGINX container. The directory on the host is mapped to the container so you will actually want to make sure your correct certificate related files are under the `./bwdata/ssl/` directory.
|
||||
**A:** High availability can be achieved by either configuring multiple instances of the containers into a Docker Swarm or Kubernetes environment, and/or by pointing the database connection string that the containers reference to any MSSQL database or cluster. Then you would probably want to load balance the NGINX containers or however you choose to handle the front-end.
|
||||
|
||||
You should only ever need to work with the files under `./bwdata/ssl/`, you do not want to work with files directly inside any container. It should line up like this (bitwarden.domain.local is only an example):
|
||||
#### Q: How do I backup and restore my self-hosted instance?
|
||||
|
||||
**A:** Bitwarden takes automated nightly backups of the `bitwarden-mssql` database container in order to protect your stored credentials. For help with manual backups, or help restoring a backup, see [Backup your Hosted Data]({% link _articles/hosting/backup-on-premise.md %}).
|
||||
|
||||
#### Q: What are my installation id and installation key used for?
|
||||
|
||||
**A:** Installation ids keys are used when installing Bitwarden on-premises in order to:
|
||||
|
||||
- Register your installation and contain email so that we can contact you for important security updates.
|
||||
- Authenticate to push relay servers for push notifications to Bitwarden client applications.
|
||||
- Validate licensing of paid features.
|
||||
|
||||
Retrieve an installation id and key from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"}.
|
||||
|
||||
**You should not share your installation id or installation key across multiple Bitwarden installations.** They should be treated as secrets.
|
||||
|
||||
#### Q: How do I change the name of my server?
|
||||
|
||||
**A:** Configure the `url:` in the `./bwdata/config.yml` with your new server name and the run the `./bitwarden.sh` rebuild command to rebuild `bwdata` assets.
|
||||
|
||||
Check that your server name or FQDN has been proliferated to all `globalSettings_baseServiceUri__*` variables in `./bwdata/env/global.override.env`, and that your certificate contains a Subject Alternative Name (SAN) with the new server FQDN
|
||||
|
||||
If you are using Let's Encrypt certificate, you'll need to [Manually Update Your Certificate](https://bitwarden.com/help/article/certificates/#manually-update-a-lets-encrypt-certificate){:target="\_blank"}.
|
||||
|
||||
## SMTP Configuration
|
||||
|
||||
#### Q: How do I set up an SMTP Mail Server?
|
||||
|
||||
**A:** Connect your self-hosted instance to an existing SMTP Mail Server by editing all `globalSettings__mail__smtp__*` values in `./bwdata/env/global.overide.env`. For more information, see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %}).
|
||||
|
||||
If you don't yet have an existing SMTP Mail Server from which you can relay emails, consider services like [Mailgun](https://www.mailgun.com/){:target="\_blank"} or [SparkPost](https://www.sparkpost.com){:target="\_blank"}, or use Gmail an SMTP Mail Server.
|
||||
|
||||
#### Q: How do I use Gmail as an SMTP Mail Server?
|
||||
|
||||
**A:** Configure the following variables in `./bwdata/env/global.override.env`:
|
||||
|
||||
```
|
||||
{ ./bwdata/config.yml }
|
||||
ssl_certificate_path: /etc/ssl/bitwarden.domain.local/certificate.crt
|
||||
ssl_key_path: /etc/ssl/bitwarden.domain.local/private.key
|
||||
ssl_ca_path: /etc/ssl/bitwarden.domain.local/ca.crt
|
||||
```
|
||||
|
||||
```
|
||||
{ ./bwdata/ssl/bitwarden.domain.local }
|
||||
ca.crt
|
||||
certificate.crt
|
||||
private.key`
|
||||
```
|
||||
Please make sure all of your CA certificates are all included in the CA certificate chain file if you have a Root CA and Intermediate CA certificate.
|
||||
|
||||
### Certificate Setup for Public CA, On-premises and self-hosted
|
||||
|
||||
You will need to create a private key for the Bitwarden server. Then you can generate a CSR. You can use OpenSSL to accomplish this. Once you have generated the CSR then you can provide it to the Certificate Authority you are using to provide your server/site certificate. After you generate your key and certs, place them in the ./bwdata/ssl directory. Then you will need to map them in ./bwdata/config.yml. When configuring your server, you will need to have three files, private key, server cert, and the ca-cert then you will configure their path in the config.yml file in the Bitwarden installation directory. The path that is defined in the config.yml is actually the location inside the NGINX container. The directory on the host is mapped to the container so you will actually want to make sure your correct certificate related files are under the ./bwdata/ssl/ directory. You should only ever need to work with the files under ./bwdata/ssl/, you do not want to work with files directly inside any container. It should line up like this (bitwarden.domain.local is only an example):
|
||||
|
||||
```
|
||||
{ ./bwdata/config.yml }
|
||||
ssl_certificate_path: /etc/ssl/bitwarden.domain.local/certificate.crt
|
||||
ssl_key_path: /etc/ssl/bitwarden.domain.local/private.key
|
||||
ssl_ca_path: /etc/ssl/bitwarden.domain.local/ca.crt
|
||||
```
|
||||
```
|
||||
{ ./bwdata/ssl/bitwarden.domain.local }
|
||||
ca.crt
|
||||
certificate.crt
|
||||
private.key
|
||||
```
|
||||
Please make sure all of your CA certificates are all included in the CA certificate chain file if you have a Root CA and Intermediate CA certificate.
|
||||
|
||||
### Change Server Name
|
||||
|
||||
In order to change the server name of your Bitwarden Server, you will need to configure the `url` in the `./bwdata/config.yml` with the new server name and the run the ./bitwarden.sh rebuild command. Next you will want to make sure the new name or FQDN has been set on all the `globalSettings__baseServiceUri__` variables in the `./bwdata/env/global.override.env` file. You will also need to make sure your certificate contains a Subject Alternative Name (SAN) with the new server FQDN.
|
||||
|
||||
If you are using a Let's Encrypt certificate, you can create a new one with the new server name by using these steps:
|
||||
```
|
||||
./bitwarden.sh stop
|
||||
mv ./bwdata/letsencrypt ./bwadata/letsencrypt_backup
|
||||
mkdir ./bwdata/letsencrypt
|
||||
chown -R bitwarden:bitwarden ./bwdata/letsencrypt
|
||||
chmod -R 740 ./bwdata/letsencrypt
|
||||
docker pull certbot/certbot
|
||||
docker run -i --rm --name certbot -p 443:443 -p 80:80 -v <Full Path from / >/bwdata/letsencrypt:/etc/letsencrypt/ certbot/certbot certonly --logs-dir /etc/letsencrypt/logs
|
||||
Select 1, then follow instructions
|
||||
openssl dhparam -out ./bwdata/letsencrypt/live/<your.domain.com>/dhparam.pem 2048
|
||||
./bitwarden.sh rebuild
|
||||
./bitwarden.sh start
|
||||
```
|
||||
|
||||
### Gmail self-hosted config
|
||||
|
||||
You can configure your Bitwarden Server to send email using your Gmail account by configuring these variable in the ./bwdata/env/global.override.env file. (Please note, with ssl=false it will default to use TLS)
|
||||
```
|
||||
globalSettings__mail__replyToEmail=no-reply@bitwarden.domain.com
|
||||
globalSettings__mail__replyToEmail=no-reply@your.domain
|
||||
globalSettings__mail__smtp__host=smtp.gmail.com
|
||||
globalSettings__mail__smtp__port=587
|
||||
globalSettings__mail__smtp__ssl=false
|
||||
globalSettings__mail__smtp__username=Gmail-username
|
||||
globalSettings__mail__smtp__password=Gmail-password
|
||||
```
|
||||
If you are using Two-Step Authentication with your Gmail account then you will need to generate an app-specific password for use with Bitwarden. You can generate an app-specific password by signing in to your Google and following their instructions. Once you have the app-specific password, enter it into Bitwarden's SMTP configuration in the ./bwdata/env/global.override.env file.
|
||||
|
||||
### High Availability
|
||||
|
||||
High availability can be achieved by either configuring multiple instances of the containers into a Docker Swarm, Kubernetes, etc. environment and/or you can point the database connection string that the containers reference to any MSSQL database or cluster. Then you would probably want to load balance the NGINX containers or however you choose to handle the front-end.
|
||||
|
||||
### Let's Encrypt Manual Update - issue or domain and server name change
|
||||
|
||||
```
|
||||
./bitwarden.sh stop
|
||||
mv ./bwdata/letsencrypt ./bwadata/letsencrypt_backup
|
||||
mkdir ./bwdata/letsencrypt
|
||||
chown -R bitwarden:bitwarden ./bwdata/letsencrypt
|
||||
chmod -R 740 ./bwdata/letsencrypt
|
||||
docker pull certbot/certbot
|
||||
docker run -i --rm --name certbot -p 443:443 -p 80:80 -v <Full Path from / >/bwdata/letsencrypt:/etc/letsencrypt/ certbot/certbot certonly --logs-dir /etc/letsencrypt/logs
|
||||
Select 1, then follow instructions
|
||||
openssl dhparam -out ./bwdata/letsencrypt/live/<your.domain.com>/dhparam.pem 2048
|
||||
./bitwarden.sh rebuild
|
||||
./bitwarden.sh start
|
||||
```
|
||||
### Migrate cloud to on-premise
|
||||
|
||||
In order to migrate your data from a Bitwarden Cloud account to a self-hosted Bitwarden Server, you will want to follow the on-premise installation instructions:
|
||||
<https://help.bitwarden.com/article/install-on-premise/>
|
||||
|
||||
Once you have completed the installation, you will need to download your Enterprise Organization license (this is written for someone doing a clean installation, you will only need to download the license from your existing Organization: <https://help.bitwarden.com/article/licensing-on-premise/#organization-account-sharing>
|
||||
|
||||
After the server is running and the Organization has been created and licensed, you will need to export your data from our servers and import it to your server: <https://help.bitwarden.com/article/export-your-data/>
|
||||
|
||||
Once you have completed the import, which will include the Collections, Items and their associations, you will need to set up the groups and users (there are several options so please check the relative links): <https://help.bitwarden.com/organizations/>
|
||||
|
||||
Please take note of the backup procedure: https://help.bitwarden.com/article/backup-on-premise/
|
||||
|
||||
## Restore Bitwarden Server Detailed and Restore From Backup
|
||||
|
||||
Do you have a full backup of the entire Bitwarden Server directory (bwdata)? If so you can simply copy that back to the server and run the normal start command.
|
||||
|
||||
If you need to restore from a SQL backup then you will want to first log into the mssql container.
|
||||
|
||||
In order to log into the container you will first need to figure out the CONTAINER ID.
|
||||
|
||||
`docker ps`
|
||||
|
||||
Note the CONTAINER ID for the bitwarden/mssql container and then log in by running:
|
||||
|
||||
`docker exec -it {CONTAINER ID} /bin/bash`
|
||||
|
||||
Once you are in the container, you will want to find the name of the latest backup file under /etc/bitwarden/mssql/backups/ and note the name of the BAK file. Now you can make a new backup file just in case. To do this you will simply run ./backup-db.sh found on the root "/" of the container
|
||||
|
||||
Now you will need to log into the mssql instance.
|
||||
|
||||
`/opt/mssql-tools/bin/sqlcmd -S localhost -U sa`
|
||||
Password: (Please note, you will want to get the database sa password from the /bwdata/env/global.override.env file on your host.)
|
||||
|
||||
```
|
||||
1> use master
|
||||
2> GO
|
||||
1> alter database vault set offline with rollback immediate
|
||||
2> GO
|
||||
1> restore database vault from disk='/etc/bitwarden/mssql/backups/vault_FULL_{Backup File Name}.BAK' with replace
|
||||
2> GO
|
||||
1> alter database vault set online
|
||||
2> GO
|
||||
1> exit
|
||||
globalSettings__mail__smtp__username=<valid-gmail-username>
|
||||
globalSettings__mail__smtp__password=<valid-gmail-password>
|
||||
```
|
||||
|
||||
You can now exit the container and then you will not need to restart the Bitwarden Server as normal.
|
||||
Whether you're a Workspace Admin or personal user of Gmail, you'll need to you'll need to enable SMTP relay from within Google. For more information, see [Google's Documentation](https://support.google.com/a/answer/176600?hl=en){:target="\_blank"}.
|
||||
|
||||
### Custom Server Ports
|
||||
If you're using Two-step Authentication for your Gmail account, you'll need to generate an app-specific password for use with Bitwarden and update the `globalSettings__mail__smtp__password=` field in `./bwdata/env/global.override.env`.
|
||||
|
||||
To use custom ports instead of 80 and 443, you will need to set the new ports in the config.yml and then run the rebuild command (./bitwarden.sh rebuild). Next you will want to make sure the custom https port has been set on all the globalSettings__baseServiceUri__ variables in the ./bwdata/env/global.override.env file.
|
||||
## Advanced Configuration
|
||||
|
||||
### SMTP Config with Mail Service Options
|
||||
#### How do I use custom server ports?
|
||||
|
||||
- Have you already configured an SMTP server in your Bitwarden's ./bwdata/env/global.override.env file? You will want to check the post-install steps which cover SMTP configuration:
|
||||
<https://help.bitwarden.com/article/install-on-premise/#post-install-environment-configuration>
|
||||
**A:** To use custom ports, instead of 80 and 443, edit the `http_port=` and `https_port=` values in `./bwdata/config.yml` and run `./bitwarden.sh rebuild` to rebuild your server assets.
|
||||
|
||||
If you edit the ./bwdata/env/global.override.env file on your server, you will want to set the globalSettings__mail__smtp__ variables.
|
||||
Check that the custom port values have been proliferated to `./bwdata/env/global.override.env`.
|
||||
|
||||
- Do you currently have a mail server or a mail service you currently use which can relay email from your Bitwarden server? If you don't then you may want to consider a service such as Mailgun (<https://www.mailgun.com/>) or SparkPost (<https://www.sparkpost.com/>) which allows for many relayed emails for free per month.
|
||||
#### Q: How do I add Bitwarden to system boot?
|
||||
|
||||
### Trust a private CA issued or Self-signed certificate for Bitwarden Client
|
||||
**A:** Complete the following steps:
|
||||
|
||||
1. Create a Bitwarden service file:
|
||||
|
||||
When using a self-signed certificate, you will need to add the certificate to your OS's Trusted Root Certification Authorities Store. Are you running the Directory Connector on Windows or Linux? If you are using Windows then you can simply run certmgr.msc and then import the certificate into the correct store/folder. If you are using Linux then you will want to add the certificate to these directories:
|
||||
```
|
||||
/usr/local/share/ca-certificates/
|
||||
/usr/share/ca-certificates/
|
||||
sudo vi bitwarden.service [Unit] Description=Bitwarden Requires=docker.service
|
||||
After=docker.service [Service] Type=oneshot User=bitwarden Group=bitwarden
|
||||
ExecStart=<your-install-directory>/bitwarden.sh start RemainAfterExit=true
|
||||
ExecStop=<your-install0durectory>/bitwarden.sh stop [Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
2. Copy the Bitwarden service file to systemd:
|
||||
|
||||
Then run these commands:
|
||||
```
|
||||
sudo dpkg-reconfigure ca-certificates
|
||||
sudo update-ca-certificates
|
||||
sudo cp bitwarden.service /etc/systemmd/system/bitwarden.service
|
||||
```
|
||||
3. Set permission on the Bitwarden service file under systemd:
|
||||
|
||||
Once you have trusted the certificate then you will need to close the client/app and relaunch it.
|
||||
```
|
||||
sudo chmod 644 /etc/systemd/system/bitwarden.service
|
||||
```
|
||||
4. Optionally, reload for testing:
|
||||
|
||||
The CLI and BWDC CLI are written in Node.js, a private CA certificate or self-signed certificate, if being used, will need to be trusted using one of the following environment variables:
|
||||
```
|
||||
systemctl daemon-reload
|
||||
```
|
||||
5. Enable `bitwarden.service` in the system boot:
|
||||
|
||||
Linux:
|
||||
export `NODE_EXTRA_CA_CERTS=/path/to/cert/ca.crt`
|
||||
|
||||
Windows:
|
||||
`NODE_EXTRA_CA_CERTS | C:\path\to\cert\ca.crt`
|
||||
|
||||
### Q: When does an Organization Invitation expire?
|
||||
|
||||
**A:** 5 days (If self-hosting it can be configured with `globalSettings__organizationInviteExpirationHours=120`)
|
||||
|
||||
### Q: When does an Offline Vault session expire?
|
||||
|
||||
**A:** 90 days for mobile apps, other clients are 30 days.
|
||||
|
||||
### Q: How long does an application Remember Me for 2FA?
|
||||
|
||||
**A:** 30 days
|
||||
|
||||
### Q: How long are Event Logs stored?
|
||||
|
||||
**A:** A retention policy is not configurable at this time.
|
||||
```
|
||||
sudo systemctl enable bitwarden.service
|
||||
```
|
||||
|
||||
@@ -1,45 +1,44 @@
|
||||
---
|
||||
layout: article
|
||||
title: Using the system administrator portal
|
||||
title: System Administrator Portal
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, admin]
|
||||
order: 09
|
||||
---
|
||||
|
||||
As the system administrator of your Bitwarden installation you can use the **Admin Portal** to do things like:
|
||||
The Bitwarden System Administrator Portal can be used to:
|
||||
|
||||
- View installation environment settings
|
||||
- View the currently installed and latest available versions
|
||||
- Browse all registered users and information about them
|
||||
- Delete registered users
|
||||
- Browse all organizations and information about them
|
||||
- Delete organizations
|
||||
- Check currently installed and latest available versions.
|
||||
- View Environment Configuration settings (for more information, see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %})).
|
||||
- View and delete registered users.
|
||||
- View and delete registered Organizations.
|
||||
|
||||
{% callout info %}
|
||||
Admins cannot globally view sensitive data that is protected (encrypted) in a user's or organization's vault.
|
||||
Provisioned admins cannot view sensitive data that is protected (encrypted) in any user's or Organization's vault.
|
||||
{% endcallout %}
|
||||
|
||||
The admin portal for your installation is available at https://bitwarden.example.com/admin.
|
||||
## Configure Users for the Admin Portal
|
||||
|
||||
## Configuring Admin Portal Access
|
||||
Configure access to the Admin Portal by editing the environment file, located at `./bwdata/env/global.override.env`.
|
||||
|
||||
The admin portal provides authenticated access to a list of users specified by email address in your installation's environment file located at `./bwdata/env/global.override.env`. For example:
|
||||
Adding an email address to `adminSettings__admins=`, located at the bottom of `global.override.env`, will provide access to the Admin Portal from that email address. You can provision multiple admins using this field, for example:
|
||||
|
||||
```
|
||||
adminSettings__admins=john@example.com,bill@gmail.com,tom@example.com
|
||||
```
|
||||
|
||||
These admin email addresses **do not** need to be registered with an account on your Bitwarden installation.
|
||||
These email addresses **do not** need to be registered with an account on your Bitwarden instance.
|
||||
|
||||
If you do not want to enable access to the admin portal, you can leave the setting at its default empty value. For example:
|
||||
### Configure SMTP Mail Server
|
||||
|
||||
```
|
||||
adminSettings__admins=
|
||||
```
|
||||
The System Adminstrator Portal uses email to provide secure links for authentication. Therefore, you will need to configure your installation's SMTP Mail Server settings prior to attempting to log in to the portal. For more information, see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %}).
|
||||
|
||||
The admin portal uses a secure means of *passwordless authentication*. When a user attempts to log into the admin portal a secure link is sent to their email address. The user can click this temporary link to continue logging into the admin portal. The authentication link is active for up to **15 minutes** following the log in attempt.
|
||||
## Access the Admin Portal
|
||||
|
||||
{% callout info %}
|
||||
Since the admin portal uses email to provide secure links for authentication, you need to [configure your installation's SMTP mail settings]({% link _articles/hosting/install-on-premise.md %}) prior to attempting to log into the admin portal.
|
||||
{% endcallout %}
|
||||
The System Administrator Portal for your instance is available at `https://your.domain.com/admin`.
|
||||
|
||||
The Portal uses a secure means of *passwordless authentication*. When a user attempts to log in, a secure link is sent to their email address **only** if that email address is specified in `adminSettings__admins=`.
|
||||
|
||||
Clicking this temporary link will log that user into the System Adminstrator Portal. The link is active for 15 minutes following the login attempt.
|
||||
|
||||
@@ -1,51 +1,88 @@
|
||||
---
|
||||
layout: article
|
||||
title: Backing up your on-premises hosted data
|
||||
title: Backup your Hosted Data
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, backup]
|
||||
order: 07
|
||||
---
|
||||
|
||||
With the public cloud version of Bitwarden, we automatically handle backing up your data for you. However, when self-hosting Bitwarden you must implement your own backup procedures in order to keep your data safe.
|
||||
When self-hosting Bitwarden, you are responsible for implementing your own backup procedures in order to keep data safe.
|
||||
|
||||
Bitwarden's Docker containers use volume mapping to keep all important data persisted on the host machine. You can find this data in the `./bwdata` directory relative to your Bitwarden installation. The Docker containers themselves are to be considered ephemeral and do not persist data or state.
|
||||
## About Hosted Data
|
||||
|
||||
You should back up and keep the entire `./bwdata` directory safe. In the event of data loss you will need all or parts of data contained in this directory to restore your installation.
|
||||
Bitwarden's Docker containers use volume mapping to persist all important data on the host machine, meaning stopping your containers will not delete any data. Docker containers, on the other hand, are to be considered ephemeral and do not persist data or state.
|
||||
|
||||
Some particularly important parts of the `./bwdata` directory are:
|
||||
All Bitwarden data is stored on the host machine in the `./bwdata` directory, relative to the location in which you installed Bitwarden. For more information, see [Install and Deploy](https://bitwarden.com/help/article/install-on-premise/#install-bitwarden).
|
||||
|
||||
- `./bwdata/mssql/data` - database data
|
||||
- `./bwdata/core/attachments` - vault item attachments
|
||||
- `./bwdata/env` - environment variables, including database and certificate passwords
|
||||
## Backup Hosted Data
|
||||
|
||||
## Nightly database backups
|
||||
It's recommended that you backup and keep safe the entire `./bwdata` directory. In the event of data loss, you will need all or parts of the data contained in this directory to restore your instance.
|
||||
|
||||
Bitwarden will automatically take nightly backups of the `mssql` container database. These database backups are kept in the `./bwdata/mssql/backups` directory. Nightly database backups are kept in this directory for 30 days. In the event of data loss, you can restore one of these daily backups.
|
||||
Particularly important pieces of `./bwdata` to backup regularly include:
|
||||
|
||||
### Restoring a nightly backup
|
||||
- `./bwdata/env` - Instance's environment variables, including database and certificate passwords.
|
||||
- `./bwdata/core/attachments` - Instance's Vault item attachments.
|
||||
- `./bwdata/mssql/data` - Instance's database data.
|
||||
|
||||
1. First log into `bitwarden-mssql` container. In order to log into the container you will first need to figure out the container ID.
|
||||
Bitwarden will automatically take nightly backups of the `mssql` database container, when running.
|
||||
|
||||
docker ps
|
||||
### Nightly Database Backups
|
||||
|
||||
2. Note the container ID, and execute an interactive bash shell on the `bitwarden-mssql` container.
|
||||
Bitwarden will automatically take nightly backups of the `mssql` container database. These backups are kept in the `./bwdata/mssql/backups` directory for 30 days.
|
||||
|
||||
In the event of data loss, you can use `./bwdata/mssql/backups` to restore a nightly backup.
|
||||
|
||||
### Restore a Nightly Backup
|
||||
|
||||
In the event of data loss, complete the following steps to restore a nightly backup.
|
||||
|
||||
1. Retrieve your database password from the `globalSettings__sqlServer__connectionString=...Password=` value found in `global.override.env`.
|
||||
2. Identify the Container ID of the `mssql` container using the `docker ps` command.
|
||||
3. Run the following commmand to open a bash session for your `mssql` docker container:
|
||||
|
||||
```
|
||||
docker exec -it bitwarden-mssql /bin/bash
|
||||
```
|
||||
|
||||
3. Take note of the backup file you wish to restore in the nightly backups directory. The backups directory is mapped from a host volume at `./bwdata/mssql/backups` to `/etc/bitwarden/mssql/backups` within the `bitwarden-mssql` container.
|
||||
Your command prompt should now match the identified Container ID of the `bitwarden-mssql` container.
|
||||
4. In the container, locate the backup file you wish to restore.
|
||||
|
||||
ls /etc/bitwarden/mssql/backups
|
||||
{% callout info %}The backup directory in the container is volume-mapped from the host directory. `./bwdata/mssql/backups` on the host machine maps to `etc/bitwarden/mssql/backups` in the container.
|
||||
{% endcallout %}
|
||||
|
||||
For this example, the backup we will be using is named `vault_FULL_20200302_235901.BAK`, which is a backup of the vault database on March 2, 2020 at 11:53pm. The full path of the backup in the container would be `/etc/bitwarden/mssql/backups/vault_FULL_20200302_235901.BAK`
|
||||
For example, a file `/etc/bitwarden/mssql/backups/vault_FULL_20201208_003243.BAK` is a backup taken on December 08, 2020 at 12:32am.
|
||||
|
||||
4. Execute `sqlcmd` with the required authentication. Please note that you will want to get the database sa password from the `./bwdata/env/global.override.env` file on your host.
|
||||
5. Start the `sqlcmd` Utility with the following command:
|
||||
|
||||
/opt/mssql-tools/bin/sqlcmd -S localhost -U sa -P ${SA_PASSWORD}
|
||||
```
|
||||
/opt/mssql-tools/bin/sqlcmd -S localhost -U <sa> -P <sa-password>
|
||||
```
|
||||
|
||||
5. Execute the SQL command `RESTORE DATABASE` with your backup to restore the nightly backup, followed by a `GO` command.
|
||||
where `<sa>` and `<sa-password>` match the `User=` and `Password=` values found in `global.override.env`.
|
||||
6. Once in the `sqlcmd` Utility, you have 2 options for backup:
|
||||
|
||||
RESTORE DATABASE vault FROM DISK = '/etc/bitwarden/mssql/backups/vault_FULL_20200302_235901.BAK' WITH REPLACE
|
||||
GO
|
||||
1. **Offline Restore** (*Preferred*)
|
||||
|
||||
Your Bitwarden database should now be restored.
|
||||
Run the following SQL commands:
|
||||
```
|
||||
1> use master
|
||||
2> GO
|
||||
1> alter database vault set offline with rollback immediate
|
||||
2> GO
|
||||
1> restore database vault from disk='/etc/bitwarden/mssql/backups/vault_FULL_{Backup File Name}.BAK' with replace
|
||||
2> GO
|
||||
1> alter database vault set online
|
||||
2> GO
|
||||
1> exit
|
||||
```
|
||||
Restart your Bitwarden instance to finish restoring.
|
||||
2. **Online Restore**
|
||||
|
||||
Execute the following SQL commands:
|
||||
```
|
||||
1> RESTORE DATABASE vault FROM DISK = '/etc/bitwarden/mssql/backups/vault_FULL_20200302_235901.BAK' WITH REPLACE
|
||||
2> GO
|
||||
```
|
||||
Restart your Bitwarden instance to finish restoring.
|
||||
|
||||
123
_articles/hosting/certificates.md
Normal file
123
_articles/hosting/certificates.md
Normal file
@@ -0,0 +1,123 @@
|
||||
---
|
||||
layout: article
|
||||
title: Certificate Options
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, install, deploy]
|
||||
order: 04
|
||||
---
|
||||
|
||||
This article defines the certificate options available to Self-hosted instances of Bitwarden. You will select your certificate option during installation. For installation instructions, see [Install and Deploy On-premise]({% link _articles/hosting/install-on-premise.md %}).
|
||||
|
||||
## Generate a Certificate with Let's Encrypt
|
||||
|
||||
[Let's Encrypt](https://letsencrypt.org.how-it-works/){:target="_blank"} is a Certificate Authority (CA) that issues trusted SSL certificates free of charge for any domain. The Bitwarden installation script offers the option to generate a trusted SSL certificate for your domain using Let's Encrypt and [Certbot](https://certbot.eff.org){:target="_blank"}.
|
||||
|
||||
Certificate renewal checks occur each time Bitwarden is restarted. Using Let's Encyrpt will require you to enter an email address for certificate expiration reminders.
|
||||
|
||||
Using Let's Encrypt requires ports 80 and 443 to be open on your machine.
|
||||
|
||||
### Manually Update a Let's Encrypt Certificate
|
||||
|
||||
If you change the domain name of your Bitwarden server, you will need to manually update your generated certificate. Run the following commands to create a backup, update your certificate, and rebuild Bitwarden:
|
||||
|
||||
```
|
||||
./bitwarden.sh stop
|
||||
mv ./bwdata/letsencrypt ./bwadata/letsencrypt_backup
|
||||
mkdir ./bwdata/letsencrypt
|
||||
chown -R bitwarden:bitwarden ./bwdata/letsencrypt
|
||||
chmod -R 740 ./bwdata/letsencrypt
|
||||
docker pull certbot/certbot
|
||||
docker run -i --rm --name certbot -p 443:443 -p 80:80 -v <Full Path from / >/bwdata/letsencrypt:/etc/letsencrypt/ certbot/certbot certonly --logs-dir /etc/letsencrypt/logs
|
||||
Select 1, then follow instructions
|
||||
openssl dhparam -out ./bwdata/letsencrypt/live/<your.domain.com>/dhparam.pem 2048
|
||||
./bitwarden.sh rebuild
|
||||
./bitwarden.sh start
|
||||
```
|
||||
|
||||
## Use an Existing SSL Certificate
|
||||
|
||||
You may alternatively opt to use an existing SSL Certificate, which will require you to have the following files:
|
||||
|
||||
- A Server Certificate (`certificate.crt`)
|
||||
- A Private Key (`private.key`)
|
||||
- A CA Certificate (`ca.crt`)
|
||||
|
||||
You may need to bundle your primary certificate with Intermediate CA certificates to prevent SSL trust errors. All CA Certificates should be included in the CA Certificate Chain file when using a Root CA and Intermediate CA certificate.
|
||||
|
||||
|
||||
Under the default configuration, place your files in `./bwdata/ssl/your.domain`. You may specify a different location for your certificate files by editing the following values in `./bwdata/config.yml`:
|
||||
|
||||
```
|
||||
ssl_certificate_path: <path>
|
||||
ssl_key_path: <path>
|
||||
ssl_ca_path: <path>
|
||||
```
|
||||
|
||||
{% callout info %}
|
||||
The values defined in `config.yml` represent locations inside the NGINX container. Directories on the host are mapped to directories within the NGINX container. Under the default configuration, mappings line up as follows:
|
||||
|
||||
The following values in `config.yml`:
|
||||
```
|
||||
ssl_certificate_path: /etc/ssl/your.domain/certificate.crt
|
||||
ssl_key_path: /etc/ssl/your.domain/private.key
|
||||
ssl_ca_path: /etc/ssl/your.domain/ca.crt
|
||||
```
|
||||
|
||||
Map to the following files on the host:
|
||||
```
|
||||
./bwdata/ssl/your.domain/certificate.crt
|
||||
./bwdata/ssl/your.domain/private.key
|
||||
./bwdata/ssl/your.domain/ca/crt
|
||||
```
|
||||
|
||||
**You should only ever need to work with files in `./bwdata/ssl/`. Working with files directly in the NGINX container is not recommended.**
|
||||
{% endcallout %}
|
||||
|
||||
### Using Diffie-Hellman Key Exchange
|
||||
|
||||
*Optionally*, if using Diffie Hellman Key Exchange to generate ephemeral parameters:
|
||||
|
||||
- Include a `dhparam.pem` file in the same directory.
|
||||
- Set the `ssl_diffie_hellman_path:` value in `config.yml`.
|
||||
|
||||
{% callout info %}
|
||||
You can create your own `dhparam.pem` file using OpenSSL with `openssl dhparam -out ./dhparam.pem 2048`.
|
||||
{% endcallout %}
|
||||
|
||||
## Generate a Self-signed Certificate
|
||||
|
||||
You may alternatively opt to use a self-signed certificate, however this is only recommended for testing.
|
||||
|
||||
Self-signed certificates will not be trusted by Bitwarden client applications by default. You will be required to manually install this certificate to the trusted store of each device you plan to use Bitwarden with.
|
||||
|
||||
Your self-signed certificate (`.crt`) and private key (`private.key`) can be retrieved from the `./bwdata/ssl/self/your.domain` directory.
|
||||
|
||||
### Trust a Self-signed Certificate
|
||||
|
||||
#### Windows
|
||||
|
||||
To trust a self-signed certificate on Windows, run `certmgr.msc` and import your certificate into the right store or folder.
|
||||
|
||||
#### Linux
|
||||
|
||||
To trust a self-signed certificate on Linux, add your certificate to the following directories:
|
||||
|
||||
```
|
||||
/usr/local/share/ca-certificates/
|
||||
/usr/share/ca-certificates/
|
||||
```
|
||||
|
||||
And run the following commands:
|
||||
|
||||
```
|
||||
sudo dpkg-reconfigure ca-certificates
|
||||
sudo update-ca-certificates
|
||||
```
|
||||
|
||||
## Use no Certificate
|
||||
|
||||
{% callout warning %}
|
||||
If you opt to use no certificate, you **must front your installation with a proxy that serves Bitwarden over SSL**. This is becacuse Bitwarden requires HTTPS; trying to use Bitwarden without the HTTPS protocol will trigger errors.
|
||||
{% endcallout %}
|
||||
@@ -1,19 +1,43 @@
|
||||
---
|
||||
layout: article
|
||||
title: Change your client application's environment
|
||||
title: Connect Clients to your Instance
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, environment]
|
||||
order: 10
|
||||
---
|
||||
|
||||
By default, client applications such as the browser extensions and mobile apps all talk to the Bitwarden cloud servers. If you are hosting your own bitwarden installation you will want to change your client applications to talk to your instance instead of the Bitwarden cloud servers.
|
||||
By default, Bitwarden client applications (Browser Extensions, Mobile Apps, etc.) will connect to Bitwarden-hosted servers. Client applications can be configured to connect to your self-hosted Bitwarden instance.
|
||||
|
||||
## Change Client Application Environment
|
||||
### Browser Extensions, Desktop Apps, and Mobile Apps
|
||||
|
||||
1. If you are currently logged in to your client application, log out.
|
||||
2. On the home screen of the client application, select the {% icon fa-cog %} **Settings** icon in the top left corner.
|
||||
3. Under the **Self-hosted Environment** section, enter your installation's **Server URL**. For example, if your installation domain was bitwarden.example.com, you would enter https://bitwarden.example.com for the **Server URL**.
|
||||
4. Save the environment settings and return to the home screen.
|
||||
Complete the following steps to connect your client application to your self-hosted instance:
|
||||
|
||||
You have now configured your client application to point to your self-hosted environment.
|
||||
1. Log out of the client application.
|
||||
2. On the Login screen of the client application, select the {% icon fa-cog %} **Settings** icon in the top corner.
|
||||
3. In the **Server URL** field, enter the domain name for your instance with `https://` (for example, `https://my.bitwarden.server.com`).
|
||||
|
||||
Users with unique setups may elect to specify the URL of each service independently in the **Custom Environment** section.
|
||||
4. Select the **Save** button.
|
||||
|
||||
### CLI
|
||||
|
||||
Logout using `bw logout`, and run the following command to connect the Bitwarden CLI to your self-hosted instance:
|
||||
|
||||
```
|
||||
bw config server <server-url>
|
||||
```
|
||||
|
||||
where `<server-url` is the domain name for your instance. You can read the currently configured value by not specifying a `<server-url>`.
|
||||
|
||||
Users with unique setups may elect to specify the URL of each service independently using:
|
||||
|
||||
```
|
||||
bw config --web-vault <url>
|
||||
bw config --api <url>
|
||||
bw config --identity <url>
|
||||
bw config --icons <url>
|
||||
bw config --notifications <url>
|
||||
bw config --events <url>
|
||||
```
|
||||
|
||||
49
_articles/hosting/environment-variables.md
Normal file
49
_articles/hosting/environment-variables.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
layout: article
|
||||
title: Configure Environment Variables
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, install, deploy]
|
||||
order: 05
|
||||
---
|
||||
|
||||
Some features of Bitwarden are not configured by the `bitwarden.sh` installer. Configure these settings by editing the environment file, located at `./bwdata/env/global.override.env`.
|
||||
|
||||
`global.override.env` comes pre-baked with configurable variables (see [Included Variables](#included-variables)), however there are additional variables which can be manually added (see [Optional Variables](#optional-variables)).
|
||||
|
||||
{% callout info %}
|
||||
This article will not define every environment variable, instead focusing on those used or configured by most installations.
|
||||
{% endcallout %}
|
||||
|
||||
## Included Variables
|
||||
|
||||
The following variables are among those that already exist in `global.override.env`:
|
||||
|
||||
|Variable|Description|
|
||||
|--------|-----------|
|
||||
|globalSettings__oidcIdentityClientKey=|A randomly generated OpenID Connect client key. For more information, see [OpenID Documentation](https://openid.net/specs/openid-connect-registration-1_0.html#RegistrationResponse){:target="\_blank"}.|
|
||||
|globalSettings__duo__aKey=|A randomly generated Duo akey. For more information, see [Duo's Documentation](https://duo.com/docs/duoweb#1.-generate-an-akey){:target="\_blank"}.|
|
||||
|globalSettings__yubico__clientId=|Client ID for YubiCloud Validation Service or Self-hosted Yubico Validation Server.<br><br>If YubiCloud, get your Client ID and Secret Key [here](https://upgrade.yubico.com/getapikey/){:target="\_blank"}.<br><br>If self-hosted, see Optional Variable `globalSettings__yubico__validationUrls`.|
|
||||
|globalSettings__yubico__key=|Secret Key for YubiCloud Validation Service or Self-hosted Yubico Validation Server.<br><br>If YubiCloud, get your Client ID and Secret Key [here](https://upgrade.yubico.com/getapikey/){:target="\_blank"}.<br><br>If self-hosted, see Optional Variable `globalSettings__yubico__validationUrls`.|
|
||||
|globalSettings__mail__replyToEmail=|Email address used for invitations, typically `no_reply@smpt__host`.|
|
||||
|globalSettings__mail__smtp__host=|Your SMTP Server hostname (recommended) or IP address.|
|
||||
|globalSettings__mail__smtp__port=|The SMTP port used by the SMTP Server.|
|
||||
|globalSettings__mail__smtp__ssl=| (Boolean) Whether your SMTP Server uses an encryption protocol:<br>`true` = SSL<br>`false` = TLS|
|
||||
|globalSettings__mail__smtp__username=|A valid username for the `smtp__host`.|
|
||||
|globalSettings__mail__smtp__password=|A valid password for the `smtp__host`.|
|
||||
|globalSettings__disableUserRegistration=|Specify `true` to disable new users from being added to the instance.|
|
||||
|globalSettings__hibpApiKey=|Your HaveIBeenPwned (HIBP) API Key, available [here](https://haveibeenpwned.com/API/Key).|
|
||||
|adminSettings__admins=|Email addresses which may access the [System Administrator Portal]({% link _articles/hosting/admin-portal.md%}).|
|
||||
|
||||
## Optional Variables
|
||||
|
||||
The following variables do not already exist in `global.override.env`, and can be manually added:
|
||||
|
||||
|Variable|Description|
|
||||
|--------|-----------|
|
||||
|globalSettings__mail__smtp__trustServer=|Specify `true` to explicitly trust the certificate presented by the SMTP Server (**not recommended for production**).|
|
||||
|globalSettings__mail__smtp__sslOverride=|Specify `true` to use SSL (not TLS) on port 25.|
|
||||
|globalSettings__mail__smtp__startTls=|Specify `true` to force STARTTLS (Opportunistic TLS).|
|
||||
|globalSettings__organizationInviteExpirationHours=|Specify the number of hours after which an Organization Invite will expire (`120` by default).|
|
||||
|globalSettings__yubico__validationUrls__0=|Primary URL for self-hosted Yubico Validation Server.<br><br>Add additional Validation Server URLs by creating incremented environment variables, for example `globalSettings__yubico__validationUrls__1=`, `globalSettings__yubico__validationUrls__2=`.|
|
||||
105
_articles/hosting/install-on-premise-manual.md
Normal file
105
_articles/hosting/install-on-premise-manual.md
Normal file
@@ -0,0 +1,105 @@
|
||||
---
|
||||
layout: article
|
||||
title: Install and Deploy Manually
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, install, deploy]
|
||||
order: 02
|
||||
---
|
||||
This article will walk you through the procedure to manually install and deploy Bitwarden to your own server. **Installation using the Bitwarden installation script is recommended for most users, for instructions see [Install and Deploy]({% link _articles/hosting/install-on-premise.md %})**.
|
||||
|
||||
A manual installation may be appropriate if you are intimately familiar with Docker technologies and desire more control over your Bitwarden installation.
|
||||
|
||||
{% callout warning %}
|
||||
**Manual installations should be conducted by advanced users only.**
|
||||
|
||||
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](https://github.com/bitwarden/server/releases){:target="_blank"}. You can also monitor changes to the [dependency templates](https://github.com/bitwarden/server/tree/master/util/Setup/Templates){:target="_blank"} used by the Bitwarden installation script on GitHub.
|
||||
{% endcallout %}
|
||||
|
||||
## Installation Procedure
|
||||
|
||||
Complete the following steps to install Bitwarden manually:
|
||||
|
||||
1. Download a stubbed version of Bitwarden's dependencies (`docker-stub.zip`) from the [releases pages on GitHub](https://github.com/bitwarden/server/releases){:target="_blank"}. For example:
|
||||
|
||||
```
|
||||
curl -L https://bitwarden.com/bitwarden/server/releases/download/v<version_number>/docker-stub.zip \
|
||||
-o docker-stub.zip
|
||||
```
|
||||
|
||||
2. Create a new directory named `bwdata` and extract the `docker-stub.zip` archive to it:
|
||||
|
||||
```
|
||||
unzip docker-sub.zip -d bwdata
|
||||
```
|
||||
|
||||
The created directory matches what the `./docker/docker-compose.yml` file's mapped volumes expect, however you are free to change the location of these mappings on the host machine if desired.
|
||||
|
||||
3. Edit the following environment variables in `./env/global.override.env`:
|
||||
|
||||
- `installation__id`: Your installation id retrieved from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"}.
|
||||
- `installation__key`: Your installation key retrieved from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"}.
|
||||
- `baseServiceUri__*`: The domain for your Bitwarden instance. Enter this value in all baseServiceURi fields.
|
||||
4. Generate a `.pfx` certificate file for the identity container and place it in the mapped volume directory at `./identity/identity.pfx`. 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 -certfile identity.crt -passout pass:IDENTITY_CERT_PASSWORD
|
||||
```
|
||||
5. Edit the `globalSettings__identityServer__certificatePassword` value in `./env/global.override.env` with your configured password.
|
||||
6. Copy the created files to the `./bwdata/ssl` directory.
|
||||
|
||||
The `./bwdata/ssl` directory is mapped to the NGINX container at `/etc/ssl`. The `./nginx/default.conf` can be adjusted to utilize these certificates as desired.
|
||||
|
||||
{% callout info %}Accessing the Web Vault and APIs requires HTTPS. You should provide a trusted SSL certificate to the NGINX container or front the installation with a proxy that provides a HTTPS endpoint to Bitwarden client applications.{% endcallout %}
|
||||
|
||||
Example scenario for creating a self-signed certificate as an alternative:
|
||||
|
||||
```
|
||||
mkdir ./ssl/bitwarden.example.com
|
||||
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -days 365 \
|
||||
-keyout ./ssl/bitwarden.example.com/private.key \
|
||||
-out ./ssl/bitwarden.example.com/certificate.crt \
|
||||
-reqexts SAN -extensions SAN \
|
||||
-config <(cat /usr/lib/ssl/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:bitwarden.example.com\nbasicConstraints=CA:true')) \
|
||||
-subj "/C=US/ST=New York/L=New York/O=Company Name/OU=Bitwarden/CN=bitwarden.example.com"
|
||||
```
|
||||
|
||||
7. Edit the following in `./nginx/default.conf`:
|
||||
|
||||
- `server_name` with your configured domain name.
|
||||
- In the `Content-Security-Policy` header, replace `bitwarden.example.com` with your configured domain name.
|
||||
- Add HTTPS redirects? (Where?)
|
||||
8. Generate your own random password strings for the following values in `./env/global.override.env`:
|
||||
|
||||
- `sqlServer__connectionString=...Password=RANDOM_DATABASE_PASSWORD`
|
||||
- `internalIdentityKey=RANDOM_IDENTITY_KEY`
|
||||
- `duo__akey=RANDOM_DUO_AKEY`
|
||||
|
||||
And apply the same `RANDOM_DATABASE_PASSWORD` to `value` in `./env/mssql.override.env`.
|
||||
9. Replace the domain placeholder in `./web/app-id.json` with your domain name.
|
||||
10. Configure your Environment Variables in `./env/global.override.env`.
|
||||
|
||||
At a minimum, we recommend configuring you SMTP Mail Server and Admin Portal Access. For more information, see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %}).
|
||||
|
||||
11. Map the desired user and group id for the Bitwarden containers to run under at `./env/uid.env`. For example:
|
||||
|
||||
```
|
||||
LOCAL_UID=1000
|
||||
LOCAL_GID=1000
|
||||
```
|
||||
|
||||
Otherwise, you can leave the `./env/uid.env` file empty and the containers will run as `nobody:nobody`.
|
||||
12. Start your Bitwarden instance and access it at your configured hostname:
|
||||
|
||||
docker-compose -f ./docker/docker-compose.yml up -d
|
||||
|
||||
For reference, you can find the official Bitwarden images hosted on Docker Hub at [https://hub.docker.com/u/bitwarden/](https://hub.docker.com/u/bitwarden/){:target="_blank"}.
|
||||
@@ -1,46 +1,16 @@
|
||||
---
|
||||
layout: article
|
||||
title: Installing and deploying
|
||||
title: Install and Deploy
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, install, deploy]
|
||||
order: 01
|
||||
---
|
||||
|
||||
This article will walk you through how to install and deploy Bitwarden to your own server. Because Bitwarden is a cross platform application, you can install and deploy it on Linux, macOS, and Windows machines.
|
||||
This article will walk you through the procedure to install and deploy Bitwarden to your own server. Bitwarden can be installed and deployed on Linux, macOS, and Windows machines.
|
||||
|
||||
## TL;DR
|
||||
|
||||
1. Set DNS records for a domain name pointing to your machine. Open ports 80 and 443 on the machine.
|
||||
2. Install [Docker](https://docs.docker.com/engine/installation/){:target="_blank"} and [Docker Compose](https://docs.docker.com/compose/install/){:target="_blank"}.
|
||||
3. Get an installation id and key from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"}.
|
||||
4. Install & deploy Bitwarden.
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
curl -Lso bitwarden.sh https://go.btwrdn.co/bw-sh \
|
||||
&& chmod +x bitwarden.sh
|
||||
./bitwarden.sh install
|
||||
./bitwarden.sh start
|
||||
|
||||
{% icon fa-windows %} PowerShell
|
||||
|
||||
Invoke-RestMethod -OutFile bitwarden.ps1 `
|
||||
-Uri https://go.btwrdn.co/bw-ps
|
||||
.\bitwarden.ps1 -install
|
||||
.\bitwarden.ps1 -start
|
||||
5. Adjust additional configuration settings in `./bwdata/env/global.override.env` and restart.
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
./bitwarden.sh restart
|
||||
|
||||
{% icon fa-windows %} PowerShell
|
||||
|
||||
.\bitwarden.ps1 -restart
|
||||
6. Test your deployment. Visit the web vault at your configured domain name, register a new account, and log in.
|
||||
|
||||
## Recommended Minimum System Requirements
|
||||
## System Requirements
|
||||
|
||||
- Processor: x64, 2 GHz dual core
|
||||
- Memory: 4 GB RAM (system memory)
|
||||
@@ -51,34 +21,103 @@ If you are looking for a quality provider with affordable prices, we recommend:
|
||||
|
||||
[](https://m.do.co/c/512986b01931){:target="_blank"}
|
||||
|
||||
## Configure Your Domain
|
||||
## TL;DR
|
||||
|
||||
By default, Bitwarden will be served through ports 80 (http) and 443 (https) on the localhost machine. You should open these ports so that Bitwarden can be accessed from within and/or outside of the network. You can choose different ports during installation if you like.
|
||||
The following is a summary of the Installation Procedure in this article. Links in this section will jump to detailed **Installation Procedure** sections:
|
||||
|
||||
If you are serving Bitwarden to the outside world you will need to configure a domain name with DNS records that point to your host machine (ex. bitwarden.example.com). *You should configure this domain before beginning your Bitwarden installation.*
|
||||
1. [**Configure your Domain**](#configure-your-domain). Set DNS records for a domain name pointing to your machine, and open ports 80 and 443 on the machine.
|
||||
2. [**Install Docker and Docker Compose**](#install-docker-and-docker-compose) on your machine, and complete the optional [**Docker Post-Installation**](#docker-post-installation).
|
||||
3. Retrieve an installation id and key from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"} for use in installation.
|
||||
|
||||
## Install Docker
|
||||
For more information, see [What are my installation id and installation key used for?](https://bitwarden.com/help/article/#what-are-my-installation-key-and-installation-id-used-for).
|
||||
4. [**Install Bitwarden**](#install-bitwarden) on your machine using the following sets of commands:
|
||||
|
||||
Bitwarden will be deployed and run on your machine using an array of [Docker](https://www.docker.com/what-docker){:target="_blank"} containers. Bitwarden will work equally well with Docker Community (free) and Enterprise editions. You should evaluate which edition is best for your installation. Additionally, deployment of these containers is orchestrated through the use of [Docker Compose](https://docs.docker.com/compose/){:target="_blank"}. Docker and Docker Compose must first be installed on your machine before beginning a Bitwarden installation.
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
See the following official Docker documentation for more information:
|
||||
curl -Lso bitwarden.sh https://go.btwrdn.co/bw-sh \
|
||||
&& chmod +x bitwarden.sh
|
||||
./bitwarden.sh install
|
||||
|
||||
- [Install Docker](https://docs.docker.com/engine/installation/){:target="_blank"}
|
||||
{% icon fa-windows %} PowerShell
|
||||
|
||||
Invoke-RestMethod -OutFile bitwarden.ps1 `
|
||||
-Uri https://go.btwrdn.co/bw-ps
|
||||
.\bitwarden.ps1 -install
|
||||
5. [**Configure your Environment**](#configure-your-environment) by adjusting settings in `./bwdata/env/global.override.env`.
|
||||
6. [**Start your instance**](#start-bitwarden) using the following commands:
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
./bitwarden.sh start
|
||||
|
||||
{% icon fa-windows %} PowerShell
|
||||
|
||||
.\bitwarden.ps1 -start
|
||||
6. Test your installation by opening your configured domain in a Web Browser.
|
||||
|
||||
## Installation Procedure
|
||||
|
||||
### Configure your Domain
|
||||
|
||||
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.
|
||||
|
||||
Bitwarden recommends 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.
|
||||
|
||||
### Install Docker and Docker Compose
|
||||
|
||||
Bitwarden will be deployed and run on your machine using an array of [Docker containers](https://docs.docker.com/get-started/){:target="_blank"}. 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](https://docs.docker.com/compose/){:target="_blank"}. Some Docker installations, including Windows and 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:
|
||||
|
||||
- [Install Docker Engine](https://docs.docker.com/engine/installation/){:target="_blank"}
|
||||
- [Install Docker Compose](https://docs.docker.com/compose/install/){:target="_blank"}
|
||||
|
||||
{% callout info %}
|
||||
Some Docker installations such as Windows and macOS already come with Docker Compose installed.
|
||||
{% endcallout %}
|
||||
### Docker Post-Installation (*Linux Only*)
|
||||
|
||||
For reference, you can find the official Bitwarden images hosted on Docker Hub at [https://hub.docker.com/u/bitwarden/](https://hub.docker.com/u/bitwarden/){:target="_blank"}.
|
||||
Bitwarden recommends 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.
|
||||
|
||||
## Install Bitwarden
|
||||
**These steps are Bitwarden-recommended best practices, but are not required.** For more information, see Docker's [Post-installation steps for Linux](https://docs.docker.com/engine/install/linux-postinstall/){:target="\_blank"} documentation.
|
||||
|
||||
We've made installing Bitwarden very simple. Depending on your environment (non-Windows vs. Windows) we provide Bash (Linux and macOS) and PowerShell (Windows) scripts to aide in installing and managing your Bitwarden installation. The following steps will include references for both Bash and PowerShell.
|
||||
1. Create a bitwarden user:
|
||||
|
||||
1. Download the main Bitwarden script to your machine in the desired location:
|
||||
```
|
||||
sudo adduser bitwarden
|
||||
```
|
||||
2. Create a docker group:
|
||||
|
||||
{% callout info %}All Bitwarden assets will be installed in the `./bwdata` directory relative to where the main Bitwarden script resides.{% endcallout %}
|
||||
```
|
||||
sudo groupadd docker
|
||||
```
|
||||
3. Add the bitwarden user to the docker group:
|
||||
|
||||
```
|
||||
sudo usermod -aG docker bitwarden
|
||||
```
|
||||
4. Create a bitwarden directory:
|
||||
|
||||
```
|
||||
sudo mkdir /opt/bitwarden
|
||||
```
|
||||
5. Grant full permissions for the `/opt/bitwarden` directory:
|
||||
|
||||
```
|
||||
sudo chmod -R 700 /opt/bitwarden
|
||||
```
|
||||
6. Grant the bitwarden user ownership of the `/opt/bitwarden` directory:
|
||||
|
||||
```
|
||||
sudo chown -R bitwarden:bitwarden /opt/bitwarden
|
||||
```
|
||||
|
||||
### Install Bitwarden
|
||||
|
||||
Bitwarden provides a shell script for easy installation on Linux and macOS (Bash), or Windows (PowerShell). Complete the following steps to install Bitwarden using the shell script:
|
||||
|
||||
(*Linux Only*) If you've completed the [Docker Post-Installation](#docker-post-installation) steps, do so as the `bitwarden` user from the `/opt/bitwarden` directory.
|
||||
|
||||
1. Download the Bitwarden installation script (`bitwarden.sh`) to your machine:
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
@@ -90,7 +129,7 @@ We've made installing Bitwarden very simple. Depending on your environment (non-
|
||||
Invoke-RestMethod -OutFile bitwarden.ps1 `
|
||||
-Uri https://go.btwrdn.co/bw-ps
|
||||
|
||||
2. Start the installer:
|
||||
2. Run the installer script. A `./bwdata` directory will be created relative to the location of `bitwarden.sh`.
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
@@ -100,41 +139,43 @@ We've made installing Bitwarden very simple. Depending on your environment (non-
|
||||
|
||||
.\bitwarden.ps1 -install
|
||||
|
||||
3. Complete the prompts in the installer.
|
||||
3. Complete the prompts in the installer:
|
||||
|
||||
**Installation Id/Key**
|
||||
- **Enter the domain name for your Bitwarden instance:**
|
||||
|
||||
Each Bitwarden installation configures a unique installation id and installation key. The installation id and key is used to:
|
||||
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):**
|
||||
|
||||
1. Register your installation and contact email so that we can contact you in case of important security updates.
|
||||
2. Validate licensing of paid features.
|
||||
3. Authenticate to push relay servers for push notifications to Bitwarden client applications.
|
||||
Specify `y` to 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]({% link _articles/hosting/certificates.md %}).
|
||||
|
||||
You should not share your installation id or installation key across multiple Bitwarden installations. They should be treated as secrets.
|
||||
Alternatively, specify `n` and use the **Do you have a SSL certificate to use?** option.
|
||||
|
||||
You can obtain an installation id and key from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"}.
|
||||
- **Enter your installation id:**
|
||||
|
||||
**SSL Certificate**
|
||||
Retrieve an installation id using a valid email at [https://bitwarden.com/host](https://bitwarden.com/host). For more information, see [What are my installation id and installation key used for?](https://bitwarden.com/help/article/#what-are-my-installation-key-and-installation-id-used-for).
|
||||
- **Enter your installation key:**
|
||||
|
||||
- Bitwarden can generate and maintain renewal of a trusted SSL certificate for your domain for completely free provided by [Let's Encrypt](https://letsencrypt.org){:target="_blank"} and [Certbot](https://certbot.eff.org){:target="_blank"}. Certificate renewal checks occur each time Bitwarden is restarted. Use of the automated Let's Encrypt certificate requires ports 80 and 443 to be available. Alternatively, you can manage your own Let's Encrypt certificate outside of the Bitwarden setup script and provide it using the "bring your own SSL certificate" method as described below.
|
||||
Retrieve an installation key using a valid email at [https://bitwarden.com/host](https://bitwarden.com/host). For more information, see [What are my installation id and installation key used for?](https://bitwarden.com/help/article/#what-are-my-installation-key-and-installation-id-used-for).
|
||||
- **Do you have a SSL certificate to use? (y/n):**
|
||||
|
||||
- If you already have your own SSL certificate you can place the necessary files in the `./bwdata/ssl/your.domain.com` directory. File paths for certificate assets are configurable from the `./bwdata/config.yml` file if you wish to change the default paths generated by the installer.
|
||||
- certificate.crt (required). If not done so already, you may need to bundle your primary certificate with any intermediate certificates provided by the CA or else you will receive SSL trust errors. ex. `cat domain.crt ca.crt >> certificate.crt`. [See here](https://www.google.com/search?q=nginx+ssl+bundle+certificate+and+ca){:target="_blank"} for more information.
|
||||
- private.key (required)
|
||||
- ca.crt (optional, if trusted)
|
||||
- dhparam.pem (optional, if using Diffie Hellman ephemeral parameters). You can create your own `dhparam.pem` by using OpenSSL with `openssl dhparam -out ./dhparam.pem 2048`.
|
||||
If you already have your own SSL certificate, specify `y` and place the necessary files in the `.bwdata/ssl/your.domain` directory. You will be asked whether is is a trusted SSL certificate (y/n). For more information, see [Certificate Options]({% link _articles/hosting/certificates.md %}).
|
||||
|
||||
- If you are only testing and do not have an SSL certificate, a self-signed certificate can be generated for your installation. Self-signed certificates will not be trusted by Bitwarden client applications so you will need to install this certificate to the trusted store of each device you plan to use Bitwarden with.
|
||||
Alternatively, specify `n` and 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):**
|
||||
|
||||
- If you choose not to configure Bitwarden with a SSL certificate you must front your installation with a proxy that serves the Bitwarden installation over SSL. HTTPS is required to use Bitwarden. If you try to use Bitwarden without the HTTPS protocol you will get errors.
|
||||
Specify `y` to have Bitwarden generate a self-signed certificate for you. This option is only recommended for testing. For more information, see [Certificate Options]({% link _articles/hosting/certificates.md %}).
|
||||
|
||||
## Post-install Environment Configuration
|
||||
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.
|
||||
|
||||
**Installation Config File**
|
||||
### Configure your Environment
|
||||
|
||||
The Bitwarden setup script uses settings from `./bwdata/config.yml` to generate the necessary assets for the installation to operate. More advanced installation scenarios (ex. installations behind a proxy with alternate ports) may need to make further configuration adjustments that were not provided during the standard installation prompts. Additionally, if you need to alter the initial installation settings (ex. changing the domain name used for Bitwarden) these can be made from `./bwdata/config.yml`.
|
||||
Configuring your environment involves two procedures; Installation Configuration and Environment Variable Configuration. The degree to which you will be required to configure your environment will depend on your unique needs.
|
||||
|
||||
After changing settings in `./bwdata/config.yml`, you can apply them by running:
|
||||
#### Installation Configuration
|
||||
|
||||
The Bitwarden installation script uses settings in `./bwdata/config.yml` to generate the necessary assets for installation. Some installation scenarios (e.g. installations behind a proxy with alternate ports) may require adjustments to `config.yml` that were not provided during standard installation.
|
||||
|
||||
Edit `config.yml` as necessary, and apply changes using one of the following commands:
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
@@ -144,31 +185,42 @@ After changing settings in `./bwdata/config.yml`, you can apply them by running:
|
||||
|
||||
.\bitwarden.ps1 -rebuild
|
||||
|
||||
**Environment Variables**
|
||||
#### Environment Variables
|
||||
|
||||
Some features such as a SMTP mail server settings, YubiKey OTP API credentials, HaveIBeenPwned (HIBP) breach report API key, etc. are not configured by the installer. You can find the environment file for these settings (and all others) in the following location: `./bwdata/env/global.override.env`. Edit this file and REPLACE the placeholders values for them.
|
||||
Some features of Bitwarden are not configured by the `bitwarden.sh` installer. Configure these settings by editing the environment file, located at `./bwdata/env/global.override.env`.
|
||||
|
||||
Example:
|
||||
At a minimum, you should replace the values for:
|
||||
|
||||
```
|
||||
globalSettings__yubico__clientId=294620155
|
||||
globalSettings__yubico__key=owdez88RdxVZuGbZ4fv
|
||||
globalSettings__mail__smtp__host=smtp.sendgrid.net
|
||||
globalSettings__mail__smtp__port=587
|
||||
globalSettings__mail__smtp__ssl=false
|
||||
globalSettings__mail__smtp__username=apikey
|
||||
globalSettings__mail__smtp__password=SG.YOUR.API_KEY
|
||||
...
|
||||
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=
|
||||
```
|
||||
|
||||
If you plan to use YubiKeys for two-step login, you can get your YubiKey client id and key at [https://upgrade.yubico.com/getapikey/](https://upgrade.yubico.com/getapikey/){:target="_blank"}.
|
||||
Replacing `globalSettings__mail__smtp...=` placeholders will configure the SMTP Mail Server settings that will be used to verify new users or send invitations.
|
||||
|
||||
## Start Bitwarden
|
||||
Adding an email address to `adminSettings__admins=` will provision access to the Admin Portal.
|
||||
|
||||
Once you've completed installing and configuring your Bitwarden installation you can start it up:
|
||||
After editing `global.override.env`, run one of the following commands to apply your changes:
|
||||
|
||||
{% callout info %}
|
||||
The first time you start Bitwarden it may take some time as it downloads all of the images from Docker Hub.
|
||||
{% endcallout %}
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
./bitwarden.sh restart
|
||||
|
||||
{% icon fa-windows %} PowerShell
|
||||
|
||||
.\bitwarden.ps1 -restart
|
||||
|
||||
For more information about configuring Environment Variables, see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %}).
|
||||
|
||||
### Start Bitwarden
|
||||
|
||||
Once you've completed all previous steps, start your Bitwarden instance:
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
@@ -178,17 +230,26 @@ The first time you start Bitwarden it may take some time as it downloads all of
|
||||
|
||||
.\bitwarden.ps1 -start
|
||||
|
||||
You can then verify that all containers are up and running correctly:
|
||||
|
||||
{% callout info %}
|
||||
The first time you start Bitwarden it may take some time as it downloads all of the images from Docker Hub.
|
||||
{% endcallout %}
|
||||
|
||||
Verify that all containers are running correctly:
|
||||
|
||||
```
|
||||
docker ps
|
||||
```
|
||||
|
||||
{% image hosting/docker-ps.png %}
|
||||
{% image hosting/docker-healthy.png %}
|
||||
|
||||
Congratulations! Bitwarden is now up and running at `https://your.domain.com`. Visit the web vault in your web browser to confirm. You should register a new account and log in.
|
||||
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.
|
||||
|
||||
## Script Commands
|
||||
You may now register a new account and log in. You will need to have configured `smtp` environment variables (see [Environment Variables](#environment-variable)) in order to verify the email for your new account.
|
||||
|
||||
The Bitwarden main script (`bitwarden.sh` or `bitwarden.ps1`) has the following commands available:
|
||||
## Script Commands Reference
|
||||
|
||||
The Bitwarden installation script (`bitwarden.sh` or `bitwarden.ps1`) has the following commands available:
|
||||
|
||||
{% callout info %}
|
||||
PowerShell users will run the commands with a prefixed `-` (switch). For example `.\bitwarden.ps1 -start`.
|
||||
@@ -211,57 +272,3 @@ PowerShell users will run the commands with a prefixed `-` (switch). For example
|
||||
| help | List all commands. |
|
||||
|
||||
{% endtable %}
|
||||
|
||||
## Manual Docker Installations
|
||||
|
||||
Using the provided installation script is the recommended approach for most users, however, you can also install and configure Bitwarden manually using Docker and Docker Compose. A manual installation may be appropriate if you are intimately familiar with Docker technologies and desire more control over your Bitwarden installation. A manual installation follows most of the same steps that the installation script performs for you automatically.
|
||||
|
||||
{% callout warning %}
|
||||
Manual installations are for advanced users only.
|
||||
|
||||
Manual installations lose 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`, etc. We will try to highlight these in the [release notes on GitHub](https://github.com/bitwarden/server/releases){:target="_blank"}. You can also monitor changes to the [dependency templates](https://github.com/bitwarden/server/tree/master/util/Setup/Templates){:target="_blank"} used by the Bitwarden installation script on GitHub.
|
||||
{% endcallout %}
|
||||
|
||||
1. Download a stubbed version of Bitwarden's dependencies (`docker-stub.zip`) from the [releases pages on GitHub](https://github.com/bitwarden/server/releases){:target="_blank"}.
|
||||
2. Create a new directory named `bwdata` and extract the `docker-stub.zip` archive to it. The directory structure provided matches what the `./docker/docker-compose.yml` file's mapped volumes expect, however, you are free to change the location of these mappings on the host machine if desired.
|
||||
3. Get your `installation__id` and `installation__key` from [https://bitwarden.com/host](https://bitwarden.com/host){:target="_blank"} and provide them to the application's environment variables at `./env/global.override.env`.
|
||||
4. Update the `baseServiceUri__*` and `attachment__baseUrl` application environment variables for your hostname at `./env/global.override.env`.
|
||||
5. Generate a `.pfx` certificate file for the identity container and place it in the mapped volume directory at `./identity/identity.pfx`.
|
||||
|
||||
Example:
|
||||
|
||||
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 -certfile identity.crt -passout pass:IDENTITY_CERT_PASSWORD
|
||||
|
||||
Make sure that you provide your `IDENTITY_CERT_PASSWORD` to the application's environment variables at `./env/global.override.env`.
|
||||
6. Copy your SSL certificate and keys to the `./ssl` directory. By default, this directory is mapped to the nginx container at `/etc/ssl`. The `./nginx/default.conf` can be adjusted to utilize these certificates as desired.
|
||||
|
||||
{% callout info %}Accessing the Bitwarden web vault and APIs via HTTPS is required. You should provide a trusted SSL certificate to the nginx container or front the installation with a proxy that provides a HTTPS endpoint to Bitwarden client applications.{% endcallout %}
|
||||
|
||||
Example self-signed certificate:
|
||||
|
||||
# mkdir ./ssl/bitwarden.example.com
|
||||
openssl req -x509 -newkey rsa:4096 -sha256 -nodes -days 365 \
|
||||
-keyout ./ssl/bitwarden.example.com/private.key \
|
||||
-out ./ssl/bitwarden.example.com/certificate.crt \
|
||||
-reqexts SAN -extensions SAN \
|
||||
-config <(cat /usr/lib/ssl/openssl.cnf <(printf '[SAN]\nsubjectAltName=DNS:bitwarden.example.com\nbasicConstraints=CA:true')) \
|
||||
-subj "/C=US/ST=New York/L=New York/O=Company Name/OU=Bitwarden/CN=bitwarden.example.com"
|
||||
|
||||
7. Update the `server_name`, HTTPS redirects, and `Content-Security-Policy` header with your hostname at `./nginx/default.conf`.
|
||||
8. Generate your own random password strings for the `sqlServer__connectionString` `RANDOM_DATABASE_PASSWORD`, `internalIdentityKey` `RANDOM_IDENTITY_KEY`, and `duo__aKey` `RANDOM_DUO_AKEY` and update the variables at `./env/global.override.env`. Also be sure to apply the same `RANDOM_DATABASE_PASSWORD` at `./env/mssql.override.env`
|
||||
9. Update the `app-id.json` file at `./web/app-id.json` to include your hostname's URL (ex. `https://bitwarden.example.com`).
|
||||
10. Configure your SMTP mail server and any other desired application settings at `./env/global.override.env`.
|
||||
11. Map the desired user and group id for the Bitwarden containers to run under at `./env/uid.env`.
|
||||
|
||||
Example:
|
||||
|
||||
LOCAL_UID=1000
|
||||
LOCAL_GID=1000
|
||||
|
||||
Otherwise, you can leave the `./env/uid.env` file empty and the containers will run as `nobody:nobody`.
|
||||
12. Start your Bitwarden installation and access it at your configured hostname:
|
||||
|
||||
docker-compose -f ./docker/docker-compose.yml up -d
|
||||
|
||||
@@ -1,29 +1,46 @@
|
||||
---
|
||||
layout: article
|
||||
title: Licensing for paid features
|
||||
title: License Paid Features
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, licensing]
|
||||
order: 08
|
||||
---
|
||||
|
||||
Hosting Bitwarden yourself is free. However, some features of Bitwarden require that you obtain a paid license in order to unlock.
|
||||
Self-hosting Bitwarden is free, however some features must be unlocked in your self-hosted instance with a registered license file. A license file can be obtained from the Bitwarden-hosted [Web Vault](https://vault.bitwarden.com){:target="\_blank"} by either an account with a Premium Individual subscription or by the Owner of a Families or Enterprise Organization.
|
||||
|
||||
## Premium Membership
|
||||
{% callout info %}
|
||||
The procedures in this article assume that you have already started a paid subscription to Bitwarden. If you haven't, see [What Plan is Right for Me?]({% link _articles/plans-and-pricing/what-plan-is-right-for-me.md %}).
|
||||
{% endcallout %}
|
||||
|
||||
Using premium features of Bitwarden in a self-hosted installation requires that you obtain a premium membership license.
|
||||
## Individual License
|
||||
|
||||
1. If you haven't already, purchase a premium membership by logging in to your bitwarden.com account at <https://vault.bitwarden.com> and navigating to **Settings** → **Go Premium**.
|
||||
2. Download your premium license file from <https://vault.bitwarden.com> by navigating to **Settings** → **Premium Membership** → **Download License**.
|
||||
3. Log in to the web vault of your self-hosted Bitwarden installation. Ensure that the email address used for your user account on your self-hosted installation matches the email address used on your bitwarden.com account. Also make sure that your account's email address is verified.
|
||||
4. In your self hosted installation's web vault, navigate to **Settings** → **Go Premium**.
|
||||
5. Upload the license file that you downloaded in step 2 and your user account will upgraded to premium.
|
||||
For individual users, complete the following steps to retrieve and apply a license to your self-hosted instance:
|
||||
|
||||
## Organization Account (Sharing)
|
||||
1. In the Bitwarden-hosted [Web Vault](https://vault.bitwarden.com){:target="\_blank"}, select **Settings** from the top navigation bar.
|
||||
2. Select **Premium Membership** from the left menu.
|
||||
3. Select the **Download License** button.
|
||||
4. Log in in to your self-hosted Web Vault with an email address that matches the Bitwarden-hosted account from which you downloaded the license.
|
||||
|
||||
The sharing features of Bitwarden require that you create an organization account. To create an organization in an on-premises hosted Bitwarden installation you must first obtain a **families organization** (for personal use) or **enterprise organization** (for business use) license. Only families and enterprise organization plans are eligible for on-premises hosting.
|
||||
If you haven't already, verify your email address before proceeding. You will need to have configured SMTP environment variables to do so, for more information see [Configure Environment Variables]({% link _articles/hosting/environment-variables.md %}).
|
||||
5. Select the **Settings** tab from the top navigation.
|
||||
6. Select **Go Premium** from the left menu.
|
||||
7. In the License File section, select the **Browse...** button and add your downloaded license file.
|
||||
8. Select the **Submit** button to finish applying your Premium License.
|
||||
|
||||
1. If you haven't already, purchase a families or enterprise organization plan by logging in to your bitwarden.com account at <https://vault.bitwarden.com> and navigating to **Settings** → **Organizations** → **New Organization**. If you would like to upgrade an existing organization account to a families or enterprise plan, please [contact Bitwarden support](https://bitwarden.com/contact).
|
||||
2. Download your families or enterprise organization license file from <https://vault.bitwarden.com> by navigating to your organization's admin area, then **Settings** from the organization's sub-menu, and then **Subscription** → **Download License**. Enter the [installation id]({% link _articles/hosting/install-on-premise.md %}#install-bitwarden) that matches your Bitwarden installation. You can always locate your installation id in the `./bwdata/env/global.override.env` configuration file.
|
||||
3. Log in to the web vault of your self-hosted Bitwarden installation and navigate to **Settings** → **Organizations** → **New Organization**.
|
||||
4. Upload the license file that you downloaded in step 2 and your organization account will be created.
|
||||
## Organization License
|
||||
|
||||
For Owners of a Families or Enterprise Organization, complete the following steps to retrieve and apply a license to your self-hosted instance:
|
||||
|
||||
1. Log in to your [Web Vault](https://vault.bitwarden.com){:target="\_blank"} and open your Organization.
|
||||
2. In your Organization, open the **Settings** tab and select **Subscription** from the left menu.
|
||||
3. On the **Subscription** screen, select the **Download License** button.
|
||||
|
||||
You will be prompted to enter an installation id. Enter the installation id that was used to install your self-hosted instance and select **Submit**.
|
||||
|
||||
You can retrieve your installation id from `./bwdata/env/global.override.env` or, for more information, see [Install and Deploy]({% link _articles/hosting/install-on-premise.md %}).
|
||||
4. Log in in to your self-hosted Web Vault.
|
||||
5. Start a new Organization in your self-hosted instance by selecting the {% icon fa-plus %} **Add Organization** button.
|
||||
|
||||
You will be prompted to upload a license file. Select the **Browse** button and add your downloaded license file.
|
||||
|
||||
32
_articles/hosting/migration.md
Normal file
32
_articles/hosting/migration.md
Normal file
@@ -0,0 +1,32 @@
|
||||
---
|
||||
layout: article
|
||||
title: Migration Procedures
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, docker, install, deploy]
|
||||
order: 03
|
||||
---
|
||||
|
||||
This article will walk your through migration procedures if you're moving from **Cloud to On-premises**, or from **on-premises to Cloud**.
|
||||
|
||||
## Migrate Cloud to On-premises
|
||||
|
||||
When migrating from the Cloud to an on-premises instance:
|
||||
|
||||
1. [Install and Deploy]({% link _articles/hosting/install-on-premise.md %}) Bitwarden to your on-premises server.
|
||||
2. [Download your Enterprise Organization License](https://bitwarden.com/help/article/licensing-on-premise/#organization-license) from the Cloud Web Vault and use it to [Create an Organization]({% link _articles/organizations/create-an-organization.md %}) in your on-premises instance.
|
||||
3. [Export your Data]({% link _articles/account/export-your-data.md %}) from the Cloud Web Vault.
|
||||
4. [Import your Data]({}) to your on-premisesinstance to automatically create Collections, Vault items, and their associations.
|
||||
5. [Create User Groups]({% link _articles/organizations/create-groups.md %}) manually in your on-premises instance.
|
||||
6. Start [Inviting Users to your Organization]({% link _articles/organizations/managing-users.md %}).
|
||||
|
||||
## Migrate on-premises to Cloud
|
||||
|
||||
When migrating from an on-premises instance to the Cloud:
|
||||
|
||||
1. [Create an Organization]({% link _articles/organizations/create-an-organization.md %}) in the Cloud [Web Vault](https://vault.bitwarden.com){:target="\_blank"}.
|
||||
2. [Create User Groups]({% link _articles/organizations/create-groups.md %}) and [Invite Users to your Organization]({% link _articles/organizations/managing-users.md %}) to mirror your on-premises instance.
|
||||
3. [Export your Data]({% link _articles/account/export-your-data.md %}) from your on-premises instance. Encourage your users to export their personal Vaults as well.
|
||||
4. [Import your Data]({}) to the Cloud.
|
||||
5. Manually migrate (download from on-premises and upload to Cloud) any stored attachments.
|
||||
@@ -1,15 +1,22 @@
|
||||
---
|
||||
layout: article
|
||||
title: Updating your self-hosted installation
|
||||
title: Update your Instance
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [hosting, update]
|
||||
order: 06
|
||||
---
|
||||
|
||||
It is very important to keep your Bitwarden installation up to date. Updates may include fixes that are important for the security of your Bitwarden installation. Additionally, newer versions of client applications such as the browser extension and/or mobile apps may not support older versions of your self-hosted Bitwarden server.
|
||||
**It is critically important to keep your Self-hosted Bitwarden instance up to date.**
|
||||
|
||||
We have made updating your Bitwarden installation very simple. Use the same Bitwarden Bash (macOS and Linux) or PowerShell (Windows) script that you obtained while installing Bitwarden to your server to update your Bitwarden installation. Run the following sequence of commands:
|
||||
Updates may include fixes that are important for the security of your Bitwarden instance. Additionally, newer versions of client applications may not support older versions of your self-hosted instance.
|
||||
|
||||
{% callout warning %}
|
||||
We highly recommend backing up your data before updating your self-hosted instance. For more information, see [Backup your Hosted Data]({% link _articles/hosting/backup-on-premise.md %}).
|
||||
{% endcallout %}
|
||||
|
||||
Update your Bitwarden instance using the same Bash (Linux or macOS) or Powershell (Windows) script (`bitwarden.sh`) used to install Bitwarden. Run the following sequence of commands:
|
||||
|
||||
{% icon fa-linux %} {% icon fa-apple %} Bash
|
||||
|
||||
@@ -24,5 +31,5 @@ We have made updating your Bitwarden installation very simple. Use the same Bitw
|
||||
Your Bitwarden installation should now be fully up to date and running.
|
||||
|
||||
{% callout success %}
|
||||
Create a cronjob or scheduled task to run these update commands weekly, or even nightly. This will automatically keep your installation up to date.
|
||||
We recommend creating a cronjob or scheduled task to run these update commands weekly, or even nightly. This will automatically keep your instance up to date.
|
||||
{% endcallout %}
|
||||
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
layout: article
|
||||
title: What platforms can I host on?
|
||||
categories: [hosting]
|
||||
featured: false
|
||||
popular: false
|
||||
tags: [platforms, hosting, docker]
|
||||
---
|
||||
|
||||
Bitwarden is a cross-platform application that is deployed using Docker Linux containers. This means that Bitwarden can be hosted on Linux, macOS, and Windows machines.
|
||||
|
||||
You can read more about Docker and container technologies at [https://www.docker.com/what-docker](https://www.docker.com/what-docker){:target="_blank"}.
|
||||
BIN
images/hosting/docker-healthy.png
Normal file
BIN
images/hosting/docker-healthy.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 67 KiB |
Reference in New Issue
Block a user