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 following limitations apply to both migration methods:
- Due to API incompatibility, apps that rely on the Dash Enterprise 4.X GraphQL API will probably not work when migrated to Dash Enterprise 5.X. The Platform Analytics sample app (and likely any apps based on it) is known to not work.
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, and environment variables in Dash Enterprise 5.
The scripts also create any services required by apps and update app files to convert
app.json to the file types required by Dash Enterprise 5. Note that the scripts do not update
If you plan on using an IdP with Dash Enterprise 5, use the migration scripts before setting up the IdP.
The following are not handled by the migration scripts:
- Data from mapped directories is not migrated. Mapped directories are not available in Dash Enterprise 5. 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.
To run the Dash Enterprise migration scripts:
migration_scripts: Folder containing the migration scripts.
migration: Folder to which migration data is saved as you run the scripts. This is initially empty.
.env.sample: A sample file showing how to declare the environment variables and values required by the migration scripts.
.env.sample, create a
.envfile in the root of the scripts folder. This file must contain the following:
DE5_INTERNAL_PYPI_SERVICE(only required if Dash Enterprise 5.X is airgapped)
To migrate from a Dash Enterprise 4 instance with a portal at
https://example-dash-enterprise-4-hostname.com/Portal to a Dash Enterprise 5 instance with a portal at
https://example-dash-enterprise-5-hostname.com/Portal, you’d set
DE4_ADMIN_TOKEN is your Dash Enterprise 4 API key. You’ll find it in Dash Enterprise 4 by selecting your username and then Manage API key:
DE4_SSH_USER is the username used to create the VM where Dash Enterprise 4 is deployed to. If Dash Enterprise 4 is deployed on an Azure VM, this is often
azureuser, and on AWS, it is often
DE4_SSH_PORTis the port that the migration scripts will use to SSH into your Dash Enterprise 4 VM. Usually port 22.
DE4_SSH_PRIVATE_KEY_PATHis the path to the private key that corresponds to the public key added to your Dash Enterprise 4 VM.
bash python -m venv venv
And activate it:
pip install -r requirements.txtto install the requirements for the scripts.
00_credentials.py: Generates a new RSA-SSH key pair to use for connecting to Dash Enterprise 4.
01_de4_download_data.py: Downloads information about Dash Enterprise 4 apps, users, and portal to the
migration/de4folder. If it can’t download a particular app or user, it will display a reason for the failure. If you want to inspect the output of the script, go to
migration/de4, where you’ll find a
users_de4.jsonfile with user info, an
apps_de4.jsonwith app info, a
portal.jsonfile with portal info, and a
failed_apps_de4.jsonif there were any issues downloading apps from Dash Enterprise 4.
02_de4_clone_repos.py: Clones the app code and project files for each of your Dash Enterprise 4 apps to the
migration/de4/appsfolder. When you run the script, you’ll be given the option to clone with SSH or HTTPS. When running, it gives details of the app currently being processed and how many remain to be processed.
03_convert_data.py: Converts the Dash Enterprise 4 data fetched by
01_de4_download_data.pyto a format that is compatible with Dash Enterprise 5. It saves the converted app data to
migration/de5/apps_de5.jsonand the converted user data to
04_convert_apps.py: Converts the app code and project files to file types required by Dash Enterprise 5 and saves them to
runtime.txtfiles to a
project.tomlfile, capturing any predeploy and postdeploy scripts and a Python version if specified. The Python version pinned in
project.tomlcorresponds to the major and minor version specified in
runtime.txt. For example, if the
3.7.5, it changes to
project.tomlto minimize compatibility errors.
Aptfilebased on Apt files from Dash Enterprise 4.
environment.ymlfile based on the Dash Enterprise 4
requirements.txtfile: Adding the Dash Enterprise 5 packages endpoint
05_de5_create_users.py: Creates users and groups from Dash Enterprise 4 in Dash Enterprise 5. Details on any failures will be found after the script runs in
06_de5_create_apps.py: Creates apps in Dash Enterprise 5 that the app code will be deployed to.
07_de5_attach_ssh.py: Attaches each user’s SSH key from Dash Enterprise 4 to the corresponding migrated user in Dash Enterprise 5.
08_de5_deploy_apps.py: Deploys the app code to Dash Enterprise 5.
09_de5_check_deploy_status.py: Validates that apps have been deployed. You’ll find details of any failures in
migration/de5/status.json. In this file, successfully deployed apps show as
success, apps that failed to build show as
null, and apps that built but failed to deploy show as
10_de5_redeploy_failed_apps_with_old_pip.py: (Optional) Attempts to redeploy failed apps in the
migration/de5/status.jsonfile using an older version of pip.
11_set_temp_passwords_for_users.py: Sets temporary passwords for users.
12_clean.py: Removes the contents of the directories and JSON files created during migration. If you’re partway through a migration and need to restart, run
After you’ve run the migration scripts, set up your external IdP using the Keycloak IdP setup wizard and then ask each user to complete the following steps to link their IdP user with the native auth user created by the migration scripts:
Password123!) when prompted.
09_de5_check_deploy_status.pyshows an incorrect number for successfully deployed apps on Dash Enterprise 5. See the
migration/de5/status.jsonfile for the correct numbers.
migration/de4/failed_apps_de4.jsonfile. If the scripts fail to deploy apps to Dash Enterprise 5, you’ll find details in
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:
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 Dash Enterprise 4 features are not supported in Dash Enterprise 5 and other features work differently,
meaning in many cases you’ll need to make some updates to your apps for them to run on Dash Enterprise 5.
For example, although both Dash Enterprise 4 and 5 support pip and Conda buildpacks, the buildpacks use some different files in Dash Enterprise 5.
Key differences in Dash Enterprise 5
- Different default Python, pip, and Miniconda versions.
- For Conda apps, dependencies are now specified in an
instead of with
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
- Different URL for Dash Enterprise packages (you’ll need to change any
- APT packages are now installed using one
- Pre-deploy and post-deploy scripts are configured in
project.toml instead of
See also: Dash Enterprise 5 Breaking Changes.
Here’s an overview of manual app migration:
To change your app files and structure, you can either:
- Upload your existing 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 Dash Enterprise 5.
We recommend updating all Dash Enterprise packages to their latest versions.
At a minimum, the following changes are required:
0.0.6are not supported in Dash Enterprise 5.
dash-enterprise-authand have it pinned to a specific version,
2.2.1are not supported in Dash Enterprise 5.
dash-snapshotsand have it pinned to a specific version,
In your local environment or workspace, try the following:
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
If you continue to experience issues after trying both of the above, reinstall requirements one by one in the terminal.
Both Dash Enterprise 4 and 5 provide managed Postgres and Redis services. A key difference between services in Dash Enterprise 4 and Dash Enterprise 5 is
that in Dash Enterprise 5 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 Dash Enterprise 4 apps relied on environment variables, you’ll need to add those environment variables in Dash Enterprise 5.
The process is similar in Dash Enterprise 5. See Adding Environment Variables
for full details on adding environment variables.
If you use local directory mappings for files for your Dash Enterprise 4 app,
save these files to your Dash Enterprise 5 app’s persistent filesystem.
You can reference files in an app’s persistent filesystem in your code with
See the Persistent Filesystem chapter for more details and examples.