Using Workspaces

This documentation is for Dash Enterprise.
Dash Enterprise is the fastest way to write & deploy Dash apps and
Jupyter notebooks.
10% of the Fortune 500 uses Dash Enterprise to productionize AI and
data science apps. Find out if your company is using Dash Enterprise.

Workspaces provides a VS Code-like IDE in your browser for developing a Dash app or running Jupyter notebooks.

Creating a Workspace

Workspaces are associated with apps and each app can have one workspace. To add a workspace, first select an app from the App Manager page and go to the Workspace tab.

There are two ways to create a workspace:

Creating a blank workspace

If you haven’t yet deployed this app, select Create blank workspace to get started.

Initialize from a recent commit

If you have deployed this app, you also have the option to build the workspace based on the latest or a previous commit. This is great if you want to run the current (or a previous) version of your deployed app. To do this, choose a Commit and select Create from a commit.

When you create a workspace, Dash Enterprise creates an SSH public key internally. Dash Enterprise uses this key
to authenticate your Git session with the server, allowing you to deploy from your workspace. Note that this key does not appear in your SSH Public Keys list.

Your workspace is created using the latest version of Dash Enterprise Workspaces that is available to Dash Enterprise. The latest available version depends on your environment’s network configuration and may not correspond to the latest Dash Enterprise Workspaces release.

Opening a Workspace

Once your new workspace is finished building, select Open Workspace to go to the workspace IDE. What you can do in the IDE depends on whether you are the app owner or a co-owner.

Visiting the Workspace’s Development Site

The development site is where you can view the development app (your app running in a workspace).

You can access the development site by selecting Visit Development Site in the Workspace Information section. Visit Development Site is only available when the development app is running. App owners can run a command like python app.py in the workspace terminal to start the development app. Learn more about starting and viewing the development app.

Restarting a Workspace

In some cases when working with your workspace, you’ll want to restart it. For example, to:
- Have access to environment variables that you’ve added since the workspace was created.
- Have access to services (Redis and Postgres) that you’ve added since the workspace was created.
- Stop all processes that are running in the workspace’s terminal.
- Resolve issues, such as an unresponsive workspace.

To restart a workspace, select Restart:

<img>

Uncommitted file changes in /home/workspaceuser/app and packages installed in the workspace terminal are persisted with restarts.

For more details on what restarting a workspace means, see the Restart, Rebuild, and Delete & Recreate Compared section below.

Rebuilding a Workspace

In some cases when working with your workspace, you’ll want to rebuild it. For example, to:
- Reinstall Python based on updates you’ve made to the project.toml file.
- Run pre-deploy scripts again.

To rebuild a workspace, select Rebuild Workspace from the Workspace tab. Only the app owner can rebuild its workspace.

<img>

When you rebuild your workspace, Python packages are installed from the requirements.txt file. Any packages previously installed with pip in the workspace terminal are persisted, unless your app contains a project.toml file that specifies a Python version. Uncommitted file changes in /home/workspaceuser/app and packages installed in the terminal with sudo apt-get install and sudo apt install are also persisted.

For more details on what rebuilding a workspace means, see the Restart, Rebuild, and Delete & Recreate Compared section below.

Sometimes, you may see that the Rebuild Workspace button instead says Rebuild & Update, and a notification indicates that a new version is available.

Updating a Workspace

In Dash Enterprise 5.4.X and later, new versions of Workspaces are available to you even if your administrator has not upgraded Dash Enterprise.

Note: The Rebuild & Update action is only available if your administrator has allowed communication to api.github.com and Dash Enterprise is not behind a proxy. When this communication is not allowed, you can update your existing workspaces by rebuilding them after your administrator has upgraded Dash Enterprise.

When a new version is available, select Rebuild & Update to both rebuild your workspace and apply the latest improvements.

<img>

Plotly tracks Dash Enterprise Workspaces releases in the public GitHub repository de-workspace-releases. You can use the build commit SHA in the bottom right of the workspace IDE to identify the version that your workspace uses.

Stopping a Workspace

You can stop a workspace to free up CPU and memory:

<img>

Deleting a Workspace

Only the app owner or an administrator can delete workspaces.

If you no longer need your workspace, you can delete it. Deleting removes all files in the workspace. These files are not recoverable.

If you don’t want to lose changes you made to files in the workspace, you can either:
- Deploy those changes to your Dash app (if those changes are ready for production).
- Push those changes to an external Git server like GitHub if your organization has one available.
- Download the files to your local machine.

Restart, Rebuild, and Delete & Recreate Compared

(1) If your app contains a project.toml file that specifies a Python version, then the Python packages will not persist on rebuild.

(2) APT packages that you install in the terminal with sudo apt-get install or sudo apt install are automatically added to your Aptfile, meaning they are available when you restart or rebuild the workspace. Known issue: If you are specifying an additional repository (in the terminal or Aptfile) to install APT packages from, those packages are not preserved on restart or rebuild, so you’ll need to reinstall them.

(3) An update is performed if the Rebuild button is displayed as Rebuild & Update. The Rebuild & Update action is only available if your administrator has allowed communication to api.github.com and Dash Enterprise is not behind a proxy. When this communication is not allowed or a proxy is in place, selecting Rebuild updates your workspace if your administrator has recently upgraded Dash Enterprise. An update has taken place if the build commit SHA in the bottom right of the IDE has changed.

Viewing Workspace Logs

App owners, co-owners, and administrators can view workspace build logs in the App Info.

Select Show Workspace Logs to view the build logs. Note that it can take a few seconds for them to appear.

<img>

If you are an administrator with access to the Kubernetes cluster that Dash Enterprise is installed on, you can also view workspace logs by connecting to the cluster. Then, use Lens or the kubectl commands below.

With this method, two types of workspace logs are available: build logs and debug logs. Workspace debug logs are runtime logs printed by Theia, the framework behind Dash Enterprise Workspaces. These logs are usually not very expansive, but can sometimes help with debugging.

To view a workspace’s build logs, make sure your kubectl context is set to the right cluster, and then run the following commands:

1. sh kubectl get pods -l app=workspace-<app-name> -n dash-apps | awk '{print $1}' | tail +2
   where <app-name> is the name of the app whose workspace build logs you want to view. The output is the name of the pod the workspace is running on.

2. sh kubectl logs <pod-name> dash-app-build -n dash-apps
   where <pod-name> is the name of the pod the workspace is running on.

To view a workspace’s debug logs (not available in the App Info), make sure your kubectl context is set to the right cluster, and then run the following command:

• sh kubectl logs -l app=workspace-<app-name> -n dash-apps
  where <app-name> is the name of the app whose workspace debug logs you want to view.

Other Things to Keep in Mind

• Workspaces use the same services (Redis and Postgres) as your deployed app. See Using Services With Workspaces for more information on how to structure your apps so your app’s data isn’t overwritten.

• Dash Enterprise upgrades may automatically restart your workspaces
  to apply changes to the build system or IDE. Refer to the changelog entry for
  a specific Dash Enterprise version to see whether upgrading to that version causes
  a restart of workspaces and apps.

• When git cloning an external project into the workspace, you need to
  clone the project into the existing project folder with:

git clone <https:> .

Notice the . at the end of the git clone statement. You’ll need to delete existing files first. See Cloning Into Workspaces for more.