DE4 to DE5 Migration

This guide can help you if your organization has upgraded from Dash Enterprise 4.X to Dash Enterprise 5.X and you want to migrate your users and apps.

You have two options to migrate:
- Perform an automated migration. An automated migration involves running Plotly-provided migration scripts to recreate your Dash Enterprise 4 apps and users on Dash Enterprise 5.
- Perform a manual migration. A manual migration involves creating users, updating your apps, and deploying them to Dash Enterprise 5.

Migration Scripts

The Dash Enterprise migration scripts migrate user and app data from Dash Enterprise 4 to Dash Enterprise 5. After running them, you’ll have your Dash Enterprise 4 users (including user SSH keys), apps, app viewer access settings, environment variables, and Redis and Postgres databases in Dash Enterprise 5.

The scripts also update your app files to convert runtime.txt, apt, conda-requirements.txt and app.json to the file types required by Dash Enterprise 5. Note that the scripts do not update app.py. If any changes are required in app.py, you’ll need to follow the manual steps in the Apps section below.

Prerequisite * You have administrator access to Dash Enterprise 4 and Dash Enterprise 5.

To run the Dash Enterprise migration scripts:

1. Download the scripts here to your workstation, extract them, and cd into the directory.
2. Using the same format as the .env.sample, create a .env file in the root of the scripts directory. This file must contain the following:
   * DE4_ADMIN_USERNAME
   * DE4_ADMIN_PASSWORD
   * DE4_ADMIN_TOKEN
   * DE4_HOST
   * DE5_HOST
   * DE5_KEYCLOAK_ADMIN_USERNAME
   * DE5_KEYCLOAK_ADMIN_PASSWORD
   * DE5_INTERNAL_PYPI_SERVICE (only required if Dash Enterprise 5.X is airgapped)
3. Create a virtual environment and activate it.
4. Run pip install -r requirements.txt to install the requirements for the scripts.
5. If you plan to use an external IdP with Dash Enterprise 5, go to the external_idp_migration_scripts directory. Otherwise, go to the migration_scripts directory.
6. Run the scripts one at a time in the order indicated by their numbered prefixes.

Additional Steps with an External IdP

If you plan to use Dash Enterprise 5 with an external IdP and have finished running the
external_idp_migration_scripts, you’ll have native auth users that need to be linked with the external IdP users. If you are an admin migrating on behalf of users, once you’ve enabled your external IdP in Dash Enterprise, provide each user with their temporary password (Password123). Each user must then complete these steps to link their account:

1. Log in to Dash Enterprise with your IdP username and password.
   You’ll receive a notification that an “Account already exists”.
2. Select Add to existing account.
3. Enter your native auth username and temporary password (Password123!) when prompted.
4. You’ll be asked to update your password. Enter your IdP password.

You’ll now be able to log in to Dash Enterprise with your IdP credentials.

Known Issues

• There is a known issue where running the script 06_de5_create_apps.py to create the Dash Enterprise 5 apps may show a license seat limit error even when enough license seats are available. If you encounter this issue, rerunning the script should resolve the issue.
• There is a known issue where SAML groups aren’t successfully migrated to Dash Enterprise 5, but no error is displayed.

Limitations

The following are not handled by the migration scripts.
- Workspaces are not migrated. But you can recreate a workspace from the latest commit for an app.
- Data from mapped directories is not migrated. Mapped directories are not available in Dash Enterprise. Create a persistent filesystem for an app’s data. See the Directory Mappings section below for more details.
- Postgres and Redis data is not migrated.
- If you manually migrate users before running the scripts, apps for those users won’t be migrated when the scripts run.

Troubleshooting the Migration

If you experience issues with apps running after the migration, you may need to make manual adjustments to app requirements to resolve any issues. See the Apps section below for more details.

Manual Migration

This section shows you how to manually recreate your Dash Enterprise 4 users, apps, and app configurations on Dash Enterprise 5.

Users

If you are an admin migrating apps on behalf of a developer, create an account on Dash Enterprise 5 for them and use that when creating that user’s apps.

To create an account for a developer:

1. Create a new user with a license seat.

   If your organization is planning to use an IdP with Dash Enterprise,
   ensure the username of each account matches the value in the IdP that will be mapped to the username.

2. Log in with the user’s credentials and initialize, migrate, and deploy the apps.

3. When you’re done, share the credentials with the developer and set their password to Temporary so that they’ll be prompted to change it. If the user logs in via an IdP, they’ll be asked to link the IdP account to the account you created.

Apps

Some DE4 features are not supported in DE5 and other features work differently,
meaning in many cases you’ll need to make some updates to your DE4 apps for them to run on DE5.
For example, although both DE4 and DE5 support pip and Conda buildpacks, the buildpacks use some different files in DE5.

Key differences in DE5
- Different default Python, pip, and Miniconda versions.
- For Conda apps, dependencies are now specified in an environment.yml file,
instead of with conda-requirements.txt and requirements.txt. A requirements.txt file prevents Conda-based dependencies from being installed.
- Changing the Python version is now done via a project.toml file instead of runtime.txt. In Conda,
the Python version can be set in environment.yml.
- Different URL for Dash Enterprise packages (you’ll need to change any --extra-index-urls).
- APT packages are now installed using one Aptfile.
- Pre-deploy and post-deploy scripts are configured in project.toml instead of app.json.

See also: Dash Enterprise 5.0 Breaking Changes.

1. Initialize a new app on DE5.
2. Update the app’s project structure and files to make the app DE5-compatible.
3. Add any services that the app requires.
4. Add any environment variables that the app requires.
5. If your DE4 app uses local directory mappings, update the app to instead use DE5’s persistent filesystem.
6. Important: If deploying over SSH, remove the custom port in your SSH config. DE5 uses the standard port 22 for SSH deploys, not a custom port (3022 by default) like DE4.
7. Deploy the app to DE5.

Updating Project Structure and Files

To change your app files and structure, you can either:
- Upload your existing DE4 app files to Workspaces and try running the app. If it doesn’t run, follow this guide to update it.
- Make the updates outlined here locally and then deploy the updated app to DE5.

Project Structure and File Updates

Dash Enterprise Package Compatibility

• Versions of dash-enterprise-auth prior to 0.0.6 are not supported in DE5.
  If you are using dash-enterprise-auth and have it pinned to a specific version,
  you’ll need to update it to be dash-enterprise-auth>=0.0.6.
• Versions of dash-snapshots prior to 2.2.1 are not supported in DE5.
  If you are using dash-snapshots and have it pinned to a specific version,
  you’ll need to update it to be dash-snapshots>=2.2.1.

We recommend updating all Dash packages to their latest versions.

Resolving Dependency Issues

In your local environment or workspace, try the following:

• Reduce your requirements.txt file (or environment.yml file if using Conda) to the minimal dependencies your app needs (excluding subdependencies).

• If reducing your dependencies doesn’t work, remove version numbers from your requirements.txt or environment.yml file.

• If you continue to experience issues after trying both of the above, reinstall requirements one by one in the terminal.

Adding Services

As with DE4, DE5 provides managed Postgres and Redis services. A key difference between services in DE4 and DE5 is
that in DE5 services are app-specific, meaning a Redis or Postgres service you add to an app can only be used
by that app.

For details on how to add Redis and Postgres to an app, see:

• Adding Redis to an App
• Adding Postgres to an App

Adding Environment Variables

If your DE4 apps relied on environment variables, you’ll need to add those environment variables in DE5.
The process is similar in DE5. See Adding Environment Variables
for full details on adding environment variables.

Directory Mappings

If you use local directory mappings for files for your DE4 app,
save these files to your DE5 app’s persistent filesystem.
You can reference files in an app’s persistent filesystem in your code with '../mount/<file-name>'.
See the Persistent Filesystem chapter for more details and examples.