bitwarden/help
1
0
Fork 0
mirror of https://github.com/bitwarden/help synced 2025-12-10 13:23:16 +00:00
Code Issues Releases Wiki Activity

Migration Article (#674)

Browse Source 
* more in-depth migration article, updates to adjacent info (e.g. downloading a license) (#671)

* updates per jcooks review
This commit is contained in:
fred_the_tech_writer
2021-07-14 14:59:25 -04:00
committed by GitHub
parent 3e1237de7a
commit 90fc2f65d7
3 changed files with 131 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
_articles/hosting/install-on-premise.md
View File

@@ -36,6 +36,7 @@ The following is a summary of the Installation Procedure in this article. Links
For more information, see [What are my installation id and installation key used for?](https://bitwarden.com/help/article/hosting-faqs/#general).
4. [**Install Bitwarden**](#install-bitwarden) on your machine.
5. [**Configure your Environment**](#configure-your-environment) by adjusting settings in `./bwdata/env/global.override.env`.
{% callout success %}At a minimum, configure the `globalSettings__mail__smtp...` variables to setup an email server for inviting and verifying users.{% endcallout %}
6. [**Start your instance**](#start-bitwarden).
6. Test your installation by opening your configured domain in a Web Browser.
@@ -178,7 +179,7 @@ Edit `config.yml` as necessary, and apply changes using one of the following com
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`.
At a minimum, you should replace the values for:
**At a minimum, you should replace the values for:**
```
...
@@ -191,7 +192,7 @@ globalSettings__mail__smtp__password=<placeholder>
adminSettings__admins=
```
Replacing `globalSettings__mail__smtp...=` placeholders will configure the SMTP Mail Server settings that will be used to verify new users or send invitations.
Replacing `globalSettings__mail__smtp...=` placeholders will configure the SMTP Mail Server settings that will be used to verify new users and send invitations.
Adding an email address to `adminSettings__admins=` will provision access to the Admin Portal.

48
_articles/hosting/licensing-on-premise.md
View File

@@ -8,7 +8,7 @@ tags: [hosting, licensing]
order: 08
---
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.
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 an Organization.
{% callout info %}
The procedures in this article assume that you have already started a paid subscription to Bitwarden. If you haven't, refer to [About Bitwarden Plans]({% link _articles/plans-and-pricing/about-bitwarden-plans.md %}) and [What Plan is Right for Me?]({% link _articles/plans-and-pricing/what-plan-is-right-for-me.md %}).
@@ -16,34 +16,46 @@ The procedures in this article assume that you have already started a paid subsc
## Individual License
For individual users, complete the following steps to retrieve and apply a license to your self-hosted instance:
To retrieve your license from your Cloud account and apply it to your self-hosted server:
1. In the Bitwarden-hosted [Web Vault](https://vault.bitwarden.com){:target="\_blank"}, select **Settings** from the top navigation bar.
#### Retrieve your License
1. In the Cloud [Web Vault](https://vault.bitwarden.com){:target="\_blank"}, select **Settings** from the top navigation.
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.
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.
#### Apply your License
1. Log in to your self-hosted Web Vault with an email address that matches the Cloud-hosted account from which you downloaded the license.
{% callout success %}If you haven't already, verify your email address before proceeding. You will need to have [configured SMTP-related environment variables]({{site.baseurl}}/article/environment-variables) to do so.{% endcallout %}
2. Select the **Settings** tab from the top navigation.
3. Select **Go Premium** from the left menu.
4. In the License File section, select the **Browse...** button and add the downloaded license file.
5. Select the **Submit** button to apply your Premium License.
## Organization License
For Owners of an Organization, complete the following steps to retrieve and apply a license to your self-hosted instance:
To retrieve your Organization license from your Cloud Organization and apply it to you self-hosted server:
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.
{% callout info %}
You must be an [Organization Owner]({{site.baseurl}}/article/user-types-access-control) to both retrieve and apply a license.
{% endcallout %}
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**.
#### Retrieve your License
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.
1. In the Cloud [Web Vault](https://vault.bitwarden.com){:target="\_blank"}, open your Organization.
2. Select the Organization **Settings** tab and select **Subscription** from the left menu.
3. Select the **Download License** button.
4. When prompted, enter the installation id that was used to install your self-hosted server and select **Submit**.
You will be prompted to upload a license file. Select the **Browse** button and add your downloaded license file.
If you don't know the installation id off-hand, you can retrieve it from `./bwdata/env/global.override.env`.
#### Apply your License
1. Log in to your self-hosted Web Vault with an email address that matches the Cloud-hosted account from which you downloaded the license.
2. Start a new Organization by selecting the {% icon fa-plus %} **Add Organization** button.
3. When prompted, upload the Organization license file and select **Submit**.
### Update a renewed Organization License

114
_articles/hosting/migration.md
View File

@@ -8,25 +8,107 @@ 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**.
This article will walk you through procedures for transitioning from Cloud to Self-hosted, from Self-hosted to Cloud, and from one self-hosted server to another:
## Migrate Cloud to On-premises
<ul class="nav nav-tabs" id="myTab" role="tablist">
<li class="nav-item" role="presentation">
<a class="nav-link active" id="mobtab" data-target="#mobile" role="tab" aria-controls="mobile" aria-selected="false">Cloud to Self-hosted</a>
</li>
<li class="nav-item" role="presentation">
<a class="nav-link" id="desktab" data-target="#desktop" role="tab" aria-controls="desktop" aria-selected="false">Self-hosted to Cloud</a>
</li>
<li class="nav-item" role="presentation">
<a class="nav-link" id="betab" data-target="#browserextension" role="tab" aria-controls="browserextension" aria-selected="false">Host-to-host</a>
</li>
</ul>
<div class="tab-content" id="clientsContent">
<div class="tab-pane show active" id="mobile" role="tabpanel" aria-labelledby="mobtab">
{% capture mobile_info %}
When migrating from the Cloud to an on-premises instance:
### Migrate Cloud to Self-hosted
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/about-organizations.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]({% link _articles/importing/import-data.md %}) to your on-premises instance to automatically create Collections, Vault items, and their associations.
5. [Create User Groups]({% link _articles/organizations/about-groups.md %}) manually in your on-premises instance.
6. Start [Inviting Users to your Organization]({% link _articles/organizations/managing-users.md %}).
To migrate from the Cloud to a self-hosted server:
## Migrate on-premises to Cloud
1. [Install and deploy]({{site.baseurl}}/article/install-on-premise) Bitwarden to your server. At a high-level, this procedure involves:
When migrating from an on-premises instance to the Cloud:
1. [Configuring a domain]({{site.baseurl}}/article/install-on-premise/#configure-your-domain) for Bitwarden.
2. Installing [Docker and Docker Compose]({{site.basaeurl}}/article/install-on-premise/#install-docker-and-docker-compose).
3. Running the [installation shell script]({{site.baseurl}}/article/install-on-premise/#install-bitwarden).
4. [Configuring your environment]({{site.baseurl}}/article/install-on-premise/#configure-your-environment) to setup the Admin Portal, an SMTP Server connection, and more.
2. Start your server by running `./bitwarden.sh start`.
3. Open the Cloud Web Vault and [download your license]({{site.baseurl}}/article/licensing-on-premise).
1. [Create an Organization]({% link _articles/organizations/about-organizations.md %}) in the Cloud [Web Vault](https://vault.bitwarden.com){:target="\_blank"}.
2. [Create User Groups]({% link _articles/organizations/about-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]({% link _articles/organizations/import-to-org.md %}) to the Cloud.
5. Manually migrate (download from on-premises and upload to Cloud) any stored attachments.
{% callout success %}There are separate files for an [Organization license]({{site.baseurl}}/article/licensing-on-premise/#organization-license) and an [Individual license]({{site.baseurl}}/article/licensing-on-premise/#individual-license). **You don't need both license files.** If you're migrating an Organization, you only need to retrieve the Organization license and must be an [Organization Owner]({{site.baseurl}}/article/user-types-access-control/) to do so.{% endcallout %}
4. Still in the Cloud Web Vault, [export your personal Vault data]({{site.baseurl}}/article/export-your-data/#export-a-personal-vault) or [export your Organization Vault data]({{site.baseurl}}/article/export-your-data/#export-an-organization-vault). If you're migrating an Organization, encourage your end-users to export their Personal Vaults as well.
5. Open your self-hosted Web Vault and create an account. This account **must use the same email address** as the Cloud account you downloaded the license with.
5. Still in your self-hosted Web Vault, upload your [license]({{site.baseurl}}/article/licensing-on-premise).
{% callout success %}There are separate locations in which to upload an [Organization license]({{site.baseurl}}/article/licensing-on-premise/#organization-license) versus an [Individual license]({{site.baseurl}}/article/licensing-on-premise/#individual-license). As before, only upload the one that's relevant for you.{% endcallout %}
6. Still in the self-hosted Web Vault, import data to your [Personal Vault]({{site.baseurl}}/article/import-your-data/) or [Organization Vault]({{site.baseurl}}/article/import-to-org/).
{% callout info %}Importing data to an Organization will automatically re-create your [Collections]({{site.baseurl}}/article/about-collections/) and add the relevant Vault items to them.{% endcallout %}
#### Organizations-only Next Steps
If you're migrating an Organization to a self-hosted server, continue with the following steps:
1. (**Enterprise Organizations Only**) Re-implement your [Enterprise Policy]({{site.baseurl}}/article/policies) specifications and/or configure [Login with SSO]({{site.baseurl}}/article/about-sso/).
2. Manually [re-create user Groups]({{site.baseurl}}/article/about-groups/#create-a-group) in your self-hosted Web Vault and assign them to the proper Collections.
3. Start [inviting users to your Organization]({{site.baseurl}}/article/managing-users/#invite) manually or using [Directory Connector]({{site.baseurl}}/article/directory-sync).
{% endcapture %}
{{ mobile_info | markdownify}}
</div>
<div class="tab-pane" id="desktop" role="tabpanel" aria-labelledby="desktab">
{% capture desktop_info %}
### Migrate Self-hosted to Cloud
To migrate from a self-hosted server to the Cloud:
1. Create a full backup of the `./bwdata` directory of your self-hosted Bitwarden server. In particular, you will need access to `./bwdata/core/attachments` to manually upload [file attachments]({{site.baseurl}}/article/attachments/) to the Cloud (**Step 5**).
{% callout success %} If users are exporting their Personal Vaults over a period of time, you may need to re-sync the items from your `./bwdata/core/attachments` directory to your backup location and upload any new items in the event that they change during the cut-over period.{% endcallout %}
2. In your self-hosted Web Vault, [export your personal Vault data]({{site.baseurl}}/article/export-your-data/#export-a-personal-vault) or [export your Organization Vault data]({{site.baseurl}}/article/export-your-data/#export-an-organization-vault). If you're migrating an Organization, encourage your end-users to export their Personal Vaults as well.
3. Open the Cloud Web Vault. Most users will have previously created Cloud accounts for billing purposes, so log in to that account. If you were previously a free user without a Cloud account for billing, create an account now.
{% callout success %}If you're migrating an Organization, you'll already have a Cloud Organization established for billing and licensing purposes. For smoothest transition, we recommend using this already-established Organization rather than [creating a new one]({{site.baseurl}}/article/about-organizations/#create-an-organization).{% endcallout %}
4. Still in the self-hosted Web Vault, import data to your [Personal Vault]({{site.baseurl}}/article/import-your-data/) or [Organization Vault]({{site.baseurl}}/article/import-to-org/).
{% callout info %}Importing data to an Organization will automatically re-create your [Collections]({{site.baseurl}}/article/about-collections/) and add the relevant Vault items to them.{% endcallout %}
5. Manually upload [file attachments]({{site.baseurl}}/article/attachments/) to your Personal or Organization Vault.
#### Organizations-only Next Steps
If you're migrating an Organization to the Cloud, continue with the following steps:
1. (**Enterprise Organizations Only**) Re-implement your [Enterprise Policy]({{site.baseurl}}/article/policies) specifications and/or configure [Login with SSO]({{site.baseurl}}/article/about-sso/).
2. Manually [re-create user Groups]({{site.baseurl}}/article/about-groups/#create-a-group) in the Cloud and assign them to the proper Collections.
3. Start [inviting users to your Organization]({{site.baseurl}}/article/managing-users/#invite) manually or using [Directory Connector]({{site.baseurl}}/article/directory-sync).
{% endcapture %}
{{ desktop_info | markdownify}}
</div>
<div class="tab-pane" id="browserextension" role="tabpanel" aria-labelledby="betab">
{% capture browser_extension %}
### Migrate from one host to another
To migrate from one self-hosted Bitwarden server to another:
1. Stop your existing Bitwarden server by running `./bitwarden.sh stop`. When you run this command, Bitwarden will go down for anyone currently using it.
2. Make a full copy of the `./bwdata` directory of the *old* server. This copy will be used to recreate your configuration, database, attachments, etc. on the new server.
3. [Install and deploy]({{site.baseurl}}/article/install-on-premise/) Bitwarden to your new server.
4. Once the new Bitwarden server is set up, replace the newly-created `./bwdata` directory with the copy from the old server.
5. Print the new Bitwarden server's UID by running `id -u bitwarden`.
6. Open the file `./bwdata/env/uid.env` and check that the listed values match what was printed in the previous step. If they do not match, replace *both* values with the result of `id -u bitwarden`.
7. If you specified a different server domain during **Step 2**, edit the following:
- In `./bwdata/config.yml`, change the `url:` value to the new domain.
- In `./bwdata/env/global.override.env`, change `globalSettings__baseServiceUri__vault=` to the new domain.
8. Run `./bitwarden.sh rebuild` to apply changes to `config.yml` and `global.override.env`.
9. Start your Bitwarden server with `./bitwarden.sh start`.
{% endcapture %}
{{ browser_extension | markdownify}}
</div>
</div>