From 90fc2f65d79ec6c811a97f8656c5c9a8f7cd48ae Mon Sep 17 00:00:00 2001 From: fred_the_tech_writer <69817454+fschillingeriv@users.noreply.github.com> Date: Wed, 14 Jul 2021 14:59:25 -0400 Subject: [PATCH] Migration Article (#674) * more in-depth migration article, updates to adjacent info (e.g. downloading a license) (#671) * updates per jcooks review --- _articles/hosting/install-on-premise.md | 5 +- _articles/hosting/licensing-on-premise.md | 48 +++++---- _articles/hosting/migration.md | 114 +++++++++++++++++++--- 3 files changed, 131 insertions(+), 36 deletions(-) diff --git a/_articles/hosting/install-on-premise.md b/_articles/hosting/install-on-premise.md index 7e062ea8..27210a4b 100644 --- a/_articles/hosting/install-on-premise.md +++ b/_articles/hosting/install-on-premise.md @@ -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= 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. diff --git a/_articles/hosting/licensing-on-premise.md b/_articles/hosting/licensing-on-premise.md index b6a82706..5a8786b7 100644 --- a/_articles/hosting/licensing-on-premise.md +++ b/_articles/hosting/licensing-on-premise.md @@ -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 diff --git a/_articles/hosting/migration.md b/_articles/hosting/migration.md index 0ac0d4a1..3b2527b3 100644 --- a/_articles/hosting/migration.md +++ b/_articles/hosting/migration.md @@ -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 + +
+
+{% 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}} +
+
+{% 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}} +
+
+{% 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}} +
+