Dash Enterprise 4 to 5 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.

General Limitations

• 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.

Additional note for system administrators: If, following your app and user migration, you plan to change the base domain for your Dash Enterprise 5.X instance (for example, to use the same base domain as your 4.X instance), be sure to contact us. Changing your base domain requires support from Plotly.

Migration Guide

The guide below shows you how to 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 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.
- Overriding the default Python version is done differently.
- 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.
- 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 Breaking Changes.

Here’s an overview of app migration:

1. Initialize a new app on Dash Enterprise 5.
2. Update the app’s project structure and files to make the app compatible with Dash Enterprise 5.
3. Add any services that the app requires.
4. Add any environment variables that the app requires.
5. If your Dash Enterprise 4 app uses local directory mappings, update the app to instead use Dash Enterprise 5’s persistent filesystem.
6. Important: If deploying over SSH, remove the custom port in your SSH config. Dash Enterprise 5 uses the standard port 22 for SSH deploys, not a custom port (3022 by default) like Dash Enterprise 4. No change is required if you are deploying using the Dash Enterprise CLI (Dash Enterprise 5.2.X and later) because it uses HTTPS.
7. Deploy the app to Dash Enterprise 5.

Project Structure and File Updates

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.

Dash Enterprise Package Compatibility

We recommend updating all Dash Enterprise packages to their latest versions.

At a minimum, the following changes are required:

• Versions of dash-enterprise-auth prior to 0.0.6 are not supported in Dash Enterprise 5.
  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 Dash Enterprise 5.
  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.

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

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:

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

Adding Environment Variables

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.

Directory Mappings

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 '../mount/<file-name>'.
See the Persistent Filesystem chapter for more details and examples.