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.
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:
cd
into the directory..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)pip install -r requirements.txt
to install the requirements for the scripts.external_idp_migration_scripts
directory. Otherwise, go to the migration_scripts
directory.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:
Password123!
) when prompted.You’ll now be able to log in to Dash Enterprise with your IdP credentials.
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.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.
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.
This section shows you how to manually recreate your Dash Enterprise 4 users, apps, and app configurations on Dash Enterprise 5.
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:
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.
Log in with the user’s credentials and initialize, migrate, and deploy the 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-url
s).
- 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.
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.
dash-enterprise-auth
prior to 0.0.6
are not supported in DE5.dash-enterprise-auth
and have it pinned to a specific version,dash-enterprise-auth>=0.0.6
.dash-snapshots
prior to 2.2.1
are not supported in DE5.dash-snapshots
and have it pinned to a specific version,dash-snapshots>=2.2.1
.We recommend updating all Dash packages to their latest versions.
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.
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:
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.
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.