Self-hosting

Migration Procedures

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:

To migrate from the cloud to a self-hosted server:

  1. Install and deploy Bitwarden to your server. At a high-level, this procedure involves:

    1. Configuring a domain for Bitwarden.

    2. Installing Docker and Docker Compose.

    3. Running the installation shell script.

    4. Configuring 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.

    tip

    There are separate files for an organization license and an individual license. You don't need both license files. If you are migrating an organization, you only need to retrieve the organization license and must be an organization owner to do so.

  4. Still in the cloud web vault, export your individual vault data or export your organization vault data. If you are migrating an organization, encourage your end-users to export their individual 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.

  6. Still in your self-hosted web vault, upload your license.

    tip

    There are separate locations in which to upload an organization license or an individual license. As before, only upload the one that's relevant for you.

  7. Still in the self-hosted web vault, import data to your individual vault or organization vault.

    note

    Importing data to an organization will automatically re-create your collections and add the relevant vault items to them.

Organizations-only next steps

If you are migrating an organization to a self-hosted server, continue with the following steps:

  1. (Enterprise organizations only) Re-implement your enterprise policy specifications and/or configure login with SSO.

  2. Manually re-create user groups in your self-hosted web vault and assign them to the proper collections.

  3. Start inviting users to your organization manually or using directory connector.

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 to the cloud (Step 5).

    tip

    If users are exporting their individual 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.

  2. In your self-hosted web vault, export your individual vault data or export your organization vault data. If you are migrating an organization, encourage your end-users to export their individual 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.

    tip

    If you are migrating an organization, you will 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.

  4. Still in the cloud web vault, import data to your individual vault or organization vault.

    note

    Importing data to an organization will automatically re-create your collections and add the relevant vault items to them.

  5. Manually upload file attachments to your individual or organization vault.

Organizations-only next steps

If you are migrating an organization to the cloud, continue with the following steps:

  1. (Enterprise organizations only) Re-implement your enterprise policy specifications and/or configure login with SSO.

  2. Manually re-create user groups in the cloud and assign them to the proper collections.

  3. Start inviting users to your organization manually or using directory connector.

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, and more, for the new server.

  3. Install and deploy 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.

© 2023 Bitwarden, Inc.
TermsPrivacySitemap