Migrating from Unleash Open Source to Unleash Enterprise

Learn how to move from a self-hosted Unleash Open Source instance to Unleash Enterprise. The right approach depends on where your Enterprise instance will run:

• To keep hosting Unleash yourself, upgrade your existing instance in place. You switch the Docker image, add a license key, and keep your database, users, API tokens, and SDK connections.
• To move to Unleash Cloud, including the pay-as-you-go plan, set up a new instance and move your configuration into it. You import your flags, add your users, create new API tokens, and point your applications at the new instance.

If you are coming from LaunchDarkly, another provider, or a homegrown system, see Migrating to Unleash instead. For a feature-by-feature comparison of the two editions, see Unleash Open Source and Unleash Enterprise comparison.

Choose a migration path

Both paths give you the full Enterprise feature set. They differ in how much of your existing setup carries over automatically.

For help deciding between self-hosted, hybrid, and cloud-hosted setups, see hosting options.

Migrate to self-hosted Unleash Enterprise

The Enterprise Docker image runs against the same PostgreSQL database as the open-source image. Switching images upgrades your instance in place: every flag, strategy, user, API token, and connected application continues to work, and your Unleash URL stays the same.

Prerequisites

• A license key. You receive one as part of your Enterprise trial or from your account representative.
• Access to the environment that runs the instance, such as your Docker host, Docker Compose file, or Helm values, to change the image and set the UNLEASH_LICENSE environment variable. If you prefer to install the license through the Admin UI instead, you also need Admin access to the instance.
• A recent backup of your Unleash database.

Switch to the Enterprise image

services:
  unleash:
    image: unleashorg/unleash-enterprise:<version>
    environment:
      - DATABASE_URL=postgres://user:password@db-host:5432/unleash
      - UNLEASH_LICENSE=<your-license-key>
      # ... other service config

Set up Enterprise capabilities

Your applications need no changes. Once the instance runs the Enterprise image, you can start using the capabilities that open-source Unleash does not include:

• Single sign-on and SCIM provisioning, so your team signs in through your identity provider.
• Additional projects and environments. Open-source instances are limited to one project and two environments, so this is usually the first thing teams change. See organize feature flags for guidance.
• Project roles, custom roles, and user groups through role-based access control, and change requests for approval workflows.
• Unleash Enterprise Edge for scaling SDK traffic and serving frontend applications.
• Service accounts, so scripts and the Terraform provider run with their own identity instead of a personal access token.

The user management and access controls guide walks through authentication, roles, and auditing for an Enterprise instance.

Migrate to Unleash Cloud

Unleash Cloud is a new instance with a new URL, so the migration moves configuration from your open-source instance into it rather than upgrading in place. The work falls into four areas: setting up the instance, bringing your users, moving flag configuration, and reconnecting your applications and integrations. Your applications keep working against the open-source instance until you move them, so there is no downtime.

The table shows what carries over and how:

Prerequisites

• An Unleash Cloud instance. Start a pay-as-you-go plan or free trial, or ask your account representative for an instance on an annual contract. The person who signs up becomes the first Admin.
• Admin access to your open-source instance, to export flags and to read the configuration you need to recreate.
• A list of the applications, Edge instances, CI jobs, and integrations that connect to your open-source instance. Configure > Applications on the open-source instance shows the SDKs that currently report in.

Set up the new instance

Create the structure that your flags depend on before you import anything. Imports validate against the target instance and stop when a referenced segment, custom strategy, or context field is missing.

Bring your users

User accounts are specific to an instance, so your team needs accounts on Unleash Cloud. Pick whichever of these fits how your organization manages identities:

• Single sign-on with SAML 2.0 or OpenID Connect. Select Auto-create users in the single sign-on configuration so team members get an account with a default root role the first time they sign in. This is how most teams moving to Unleash Cloud onboard their users, and it removes the need to recreate accounts by hand.
• SCIM provisioning from Okta or Microsoft Entra ID, if you want user groups and group membership to sync from your identity provider as well.
• Public invite links, which let anyone with the link sign up with the Viewer role.
• Manual creation in Admin settings > User config > Users, for small teams.

After users exist, assign roles. The open-source Admin, Editor, and Viewer roles exist in Unleash Enterprise as predefined root roles, so you can map your current assignments one to one. Enterprise adds project roles, custom roles, and user groups, which you can introduce once the migration is done.

Move your flag configuration

Export and import work per environment: one export file contains the flags you selected with their configuration in one environment. Repeat the cycle for each environment you use.

Keep these constraints in mind:

• Import files are limited to 500 kB. If an export is larger, export in batches.
• A flag that already exists in a different project on the target is rejected. Import each flag into only one project.
• Archived flags on the target block imports of flags with the same name. Delete or revive them first.
• Importing a flag that already exists in the target project overwrites its configuration, so you can re-run an import if flags changed on the open-source instance after your first export.

To script the transfer, use the export and import endpoints of the Admin API with a personal access token on each instance. The instance synchronization script shows a complete example that exports from one instance and imports into another by tag and environment.

Reconnect your applications

API tokens belong to the instance that issued them, so every SDK, Edge instance, and script needs a new token and the new URL. Unleash Cloud issues secure tokens, which are shown once at creation, so copy each token into your secrets manager immediately.

Decommission the open-source instance

When Configure > Applications on the open-source instance shows no active SDKs, take a final database backup to retain the event log and metrics history, then shut the instance down. Revoke its API tokens first if you want to be certain that no forgotten client can keep reading flags from it.

Key takeaways

• If you keep self-hosting, switch to the unleashorg/unleash-enterprise image and add a license key. Your data, users, tokens, and SDK connections carry over unchanged.
• If you move to Unleash Cloud, create segments, custom strategies, context fields, projects, and environments first, then import flags per environment.
• Bring users through single sign-on with auto-created accounts or SCIM provisioning rather than recreating them by hand.
• Every SDK, Edge instance, and script needs a new token and the new URL. Move applications one at a time while both instances hold the same configuration.
• Freeze flag changes while applications move. If a change cannot wait, make it on the open-source instance and import the environment again, so applications on both instances see the same configuration.
• Keep a final database backup of the open-source instance for its event log and metrics history.

Frequently asked questions