Skip to main content

Upgrade Unleash

This guide provides recommendations for upgrading your self-hosted Unleash instance, particularly when moving between major versions using Docker deployments.

Unleash aims to support client SDKs connecting to a server version that is one major version newer than the client, facilitating gradual upgrades.

Before you begin any major version upgrade, we strongly recommend performing a full backup of your PostgreSQL database. This ensures you can restore your instance if issues occur during the upgrade.

Upgrading from v5 to v6​

Unleash v6, released in June 2024, introduced several key changes. Ensure you address the following before or during your upgrade to v6.

Database requirement: PostgreSQL v13+​

Unleash v6 requires PostgreSQL version 13 or later. Running v6 with older PostgreSQL versions (10, 11, 12) is unsupported, though the server might start with a warning message. Plan to upgrade your PostgreSQL instance to a supported version before or alongside your Unleash upgrade.

License key required for self-hosted Enterprise​

Starting with v6, self-hosted Unleash Enterprise instances require a valid license key to function. Obtain your license key before upgrading and ensure the license key is configured correctly.

Passport libraries removed from Open Source Docker distribution​

The official unleashorg/unleash-server Docker image for Unleash Open Source no longer includes libraries previously used for certain custom authentication methods.

If you were relying on these libraries via a custom authentication hook built into a custom image based on the official one, your authentication will break.

Consider migrating to Unleash Enterprise to use single sign-on, use password-based authentication, or explore community-maintained images that may still include these dependencies if absolutely necessary.

API changes​

  • The Unleash Edge metrics endpoint /edge/metrics has been removed. If you use Unleash Edge, ensure your Edge instances are upgraded to version 19.1.3 or later before upgrading the Unleash server to v6 to maintain metrics collection. Core flag evaluation will still work with older Edge versions.
  • The legacy feature endpoint /api/feature, deprecated in v4, has been removed. Update any integrations still using this endpoint.
  • Deprecated import service: The older file-based import functionality at startup has been removed. Use the current environment import/export features or associated APIs.

Dropped Internet Explorer support​

Support for Internet Explorer has been removed, aligning with upstream dependencies (React v18) and Microsoft's end-of-support for the browser.

Deprecated custom strategies​

While still functional in v6, custom strategies are deprecated in favor of using standard strategies combined with strategy constraints. Consider migrating if possible, as constraints offer similar flexibility without requiring custom code distribution with SDKs.

High availability upgrade considerations​

If you run multiple Unleash instances in a high-availability setup and are upgrading from a version below 5.6.11 directly to version 5.7 or higher, you might experience temporary UI unavailability during a rolling upgrade while instances with different versions (<5.7 and >=5.7) are running simultaneously. SDKs are not affected.

To avoid UI downtime, perform a two-step upgrade: first, upgrade all instances to v5.6.11. Once all instances are running v5.6.11, proceed with the upgrade to v5.7 or later.

Downgrading from v5.7+ to versions below v5.7 is not straightforward and requires manual database intervention.

Requires Node.js version 20+​

If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 20 or later. Unleash v6 drops support for Node.js versions below 20, which is the active LTS at the time of release.

Upgrading from v4 to v5​

Unleash v5, released on April 27th, 2023, introduced several key changes. Ensure you address the following before or during your upgrade to v5.

Requires Node.js version 18+​

If you run Unleash from source or using a custom build environment (not the official Docker image), you must ensure your environment uses Node.js version 18 or later. Unleash v5 drops support for Node.js versions below 18, which was the active LTS at the time of release. Unleash v4 officially supported Node.js v14 and v16, both of which reached end of life in 2023.

The Google Authenticator provider for SSO removed​

The Google Authenticator, deprecated in v4, has now been removed. Migrate to using OpenID Connect instead.

If you are running a self-hosted version of Unleash and you need to temporarily re-enable the Google Authenticator SSO, you can do so by setting the GOOGLE_AUTH_ENABLED environment variable to true. If you're running a hosted version of Unleash, you'll need to contact support to request re-enabling the flag.

Default database password updated​

The Unleash default database password was updated to password.

This change should only impact development builds and initial setup. You should never use the default password in production environments.

The /api/admin/features API removed​

Most of the old features API was deprecated in v4.3 and superseded by the project API. In v5, the deprecated parts have been completely removed. The only operations remaining on that API path are those to add or remove a tag from a feature flag.

Error message structure​

Some Unleash API error messages changed their structure in v5, specifically those generated by the OpenAPI validation layer. While the structure changed to provide more human-friendly messages and align with other Unleash errors, the error codes remain the same.

Previously, validation errors looked like this:

{
  "error": "Request validation failed",
  "validation": [
    {
      "keyword": "type",
      "dataPath": ".body.parameters",
      "schemaPath": "#/components/schemas/addonCreateUpdateSchema/properties/parameters/type",
      "params": {
        "type": "object"
      },
      "message": "should be object"
    }
  ]
}

Now they look like this:

{
  "id": "37a1765f-a5a0-4371-8aa2-341f331579f9",
  "name": "ValidationError",
  "message": "Request validation failed: the payload you provided doesn't conform to the schema. Check the `details` property for a list of errors that we found.",
  "details": [
    {
      "description": "The .parameters property should be object. You sent [].",
      "path": "parameters"
    }
  ]
}

If your integrations rely on the specific structure of these validation error messages, you might need to update your error handling logic.

Upgrading from v3 to v5​

Follow along with our video demonstration on upgrading from v3 to v5 with no downtime in just a few minutes.

Upgrading from v3 to v4​

All API calls now require a token​

In Unleash Open Source v3, client SDKs did not require an API token to connect to the Unleash server. Starting with v4, API token handling, previously an Enterprise feature, was added to the Open Source version. This means that all client SDKs now need to use a client token to connect to Unleash.

Read more in the API token documentation.

Configuring Unleash​

The options for configuring Unleash changed significantly in v4. If you are manually configuring Unleash, review the updated configuring Unleash documentation.

Introduced role-based access control​

Unleash v4 introduced role-based access control (RBAC), which significantly changed the permission system.

If you implemented custom authentication for your users, you need to make the following changes to your integration:

  • The extendedPermissions option has been removed. You can no longer specify custom permissions on a per-user basis. All logged-in users must belong to a root role (Admin, Editor, or Viewer). This is handled when creating users via the userService.
  • All logged-in users need to be defined in Unleash and have a unique ID. This can be achieved by calling createUser on the userService.

Code example:

const user = userService.loginUserWithoutPassword(
  'some@getunleash.io',
  false, // autoCreateUser. Set to true if you want to create users on the fly.
);

// The user needs to be set on the current active session
req.session.user = user;

Read more about RBAC in our reference documentation.

Legacy v2 routes removed​

This is only relevant if you previously used the enableLegacyRoutes option.

In v2 you could query feature flags on /api/features. This endpoint was deprecated in v4 and we introduced two different endpoints (/api/admin/features and /api/client/features) to optimize performance and security. In v3 you could still enable the legacy routes via the enableLegacyRoutes option. This was removed in v4.

Unleash CLI removed​

Unleash no longer ships with a binary that allows you to start Unleash directly from the command line. We recommend that you run Unleash using Docker.