This guide can help you if you are a new Dash Enterprise customer looking to start with a Dash Enterprise 5 installation, or if you are upgrading from Dash Enterprise 4.X.
Dash Enterprise puts data and AI into action with the creation of production-grade data apps for your business. Python is the premier language of AI and data and Dash Enterprise is the leading vehicle for delivering Python-based, interactive insights and analytics to business users.
Dash Enterprise pricing is based on the number of instances and license seats that your organization requires.
Exact pricing is established via private offer. There are no optional features.
Plotly also offers paid Professional Services hours where app developers can
receive direct assistance to develop data apps that meet their users’ needs.
These hours are negotiated and billed separately from Dash Enterprise.
Installing Dash Enterprise is an automated process. You use a bootstrap node to run a Plotly-provided script that creates a Kubernetes cluster using kURL and installs Dash Enterprise on your server. This guide describes how to use your cloud provider’s virtual machine (VM) service to provision a VM that will act as the server, but you can still follow this guide if you already have a VM ready to go.
A bootstrap node is a machine whose only purpose is to run the script. After Dash Enterprise is installed, you can stop or decommission it. Using a fresh VM is the best practice because the script is unlikely to run into errors caused by other installed software. This guide describes how to use your cloud provider’s virtual machine to provision a VM that will serve as your bootstrap node.
You’ll be installing Dash Enterprise as the single tenant on the cluster—that is, no other software is installed on the cluster (except mandatory supporting software). Single-tenancy is well-suited for Dash Enterprise because it is a complex platform, organizing resources on the fly when developers perform tasks like deploying Dash apps and creating databases. Multi-tenancy is not currently supported.
Plotly uses Replicated to package and deliver Dash Enterprise. You’ll be interacting with the KOTS Admin Console, part of the Replicated toolset, in the configuration step of this installation. After the installation, you’ll continue to use the KOTS Admin Console for system administration such as performing Dash Enterprise upgrades.
Here are some important notices and details about supported configurations before you get started.
Before committing to an airgapped Dash Enterprise installation, make sure your organization can provide an internal index. Dash Enterprise requires that the index have a TLS/SSL certificate from a globally trusted certificate authority (CA). A common strategy is to create a mirror of pypi.org.
Important: Apps deployed to Dash Enterprise use Python 3.10.11 by default, though developers can change the Python version. For a full list of supported versions, see the App Structure page.
Similarly, if Dash app developers plan to deploy apps that depend on APT packages, you’ll need to prepare a custom APT repository with a TLS/SSL certificate from a globally trusted certificate authority (CA).
Restarting the VM: Stopping and restarting the VM that Dash Enterprise is installed on (often called parking) is not supported. The VM must be left on for Dash Enterprise to remain in a healthy state.
Changing the VM IP: Changing the internal and/or public IP of the VM after installation, such as by moving the VM to a different subnet, is not supported.
Load balancing: Dash Enterprise on a single server does not come with a load balancer. If you need to place a load balancer in front of the VM, make sure that it supports websocket connections.
Contact our Customer Success team to get started. We’ll ask you:
When we have this information, we’ll send you a tailor-made installation script as well as a link and password to a download portal from which you’ll need to download airgap bundles. Your Installation Plan is tailor-made based on your conversation with Customer Success and contains everything you need to install Dash Enterprise for your organization.
Your Installation Plan contains:
install_de_ss_airgap.sh
, which creates the Kubernetes cluster and installs Dash Enterprise as well as supporting software.config.local.sh
which contains variables used by the scripts. You’ll define some of these variables as part of the install preparation.In this step, you’ll download the airgap bundle required to install Dash Enterprise. Note that the Dash Enterprise airgap bundle is approximately 15 GB.
To download the airgap bundle:
Unzip your Installation Plan and open the config file. Edit the following variable values:
ADMIN_PASSWORD
: The password you want to set for the KOTS Admin Console.About storing and resetting this password: We recommend storing this password in your organization’s password manager, and giving access to any other members of your team who will be managing the Dash Enterprise system (notably performing upgrades and obtaining support bundles). This password is not retrievable with a
kubectl
command. It can be changed in the Admin Console UI by anyone who is able to log in with the current password. If lost, reset it by downloading the KOTS CLI and runningkubectl kots reset-password -n plotly-system
.
HOST_INTERNAL_REGISTRY
: The URL to the private container registry you are using for Dash Enterprise images.HOST_INTERNAL_REGISTRY_USER
: The username for the account you’ll use to push images to your private container registry.HOST_INTERNAL_REGISTRY_PASSWORD
: The password for the account you’ll use to push images to your private container registry.AUTH_REGISTRY_PULLS
: Leave false
if the private container registry does not require authentication to pull images. If authentication is required to pull images, change to true
.HOST_INTERNAL_REGISTRY_BASE
: If AUTH_REGISTRY_PULLS
is set to true
, provide the URL to the private container registry without namespaces. Otherwise, leave empty.INSTANCE_SSH_TARGET
: The IP address of your server (used by the installation script to SSH into the server).INSTANCE_SSH_PORT
: The port that you want to use for SSH on your server, which corresponds to the rule that you optionally added when you provisioned your server. This will be used by the installation script to remap the Linux OpenSSH daemon (sshd
) on your server to your chosen port. Remapping the sshd
is required in order for it to not conflict with the Git SSH port. If you plan to customize the Git SSH port when configuring Dash Enterprise, then there will be no conflict, and you can set INSTANCE_SSH_PORT
to 22.INSTANCE_SSH_USERNAME
: The username for the server (used by the installation script to SSH into the server).INSTANCE_SSH_IDENTITY
: The path to the SSH private key on your bootstrap node (used by the installation script to SSH into the server).SKIP_PUSH_IMAGES
: Set to true
if you have retrieved the Dash Enterprise images into your private container registry before the installation. Otherwise, leave false
.SKIP_REGISTRY_CHECK
: Set to true
if you have retrieved the Dash Enterprise images into your private container registry before the installation. Otherwise, leave false
.INSTALL_ISTIO
: Leave false
unless instructed to modify this (and allowing access to istio.io
over 443
on your bootstrap node) by our Customer Success team.KURL_PRIVATE_IP
: If your server has more than one network interface, specify the IP address for kURL to use when creating the Kubernetes cluster. If your server has a single network interface, leave this blank.If your organization uses its own custom CA (with the internal root CA certificate installed on users’ systems), you can add the internal root CA certificate to Dash Enterprise with INTERNAL_CA_CERTIFICATE
. It must be a .crt
file and contain the root certificate only—not the full chain. Provide it as follows:
INTERNAL_CA_CERTIFICATE
(optional): The path to your organization’s internal root CA certificate on the bootstrap node. If using, you’ll move the internal root CA certificate to the home directory of the bootstrap node, so set INTERNAL_CA_CERTIFICATE
to the corresponding path, taking care to include the full name of the certificate, including its .crt
extension.In this step, you’ll move the files that are required for installation to the bootstrap node. One way to do this is to use secure copy protocol (SCP).
In this step, you’ll run the installation script from your bootstrap node. This script does the following:
INSTANCE_SSH_PORT
.kURL
and moves it to your server to create the Kubernetes cluster.plotly-system
namespace, in which the core system components of Dash Enterprise will be installed.~/.kube/config
) to run kubectl
commands against the Kubernetes cluster.To create the cluster and port-forward the KOTS Admin Console:
bash install_de_ss_airgap.sh
kots
install location by Enter installation path (leave blank for /usr/local/bin)
, press Enter
to accept the default./usr/local/bin
, press y
(you will not be prompted for a password).The script takes several minutes to complete. Continue when you see the message Forwarding from 0.0.0.0:8800 -> 3000
(do not exit yet).
If you exit by mistake, restart the port-forward with
kubectl port-forward -n plotly-system svc/kotsadm --address 0.0.0.0 8800:3000
.
The next time you SSH into your Dash Enterprise server, you’ll need to append the new SSH port to the ssh
command.
Now that your cluster is created, you’re ready to install Dash Enterprise on it. The KOTS Admin Console will take you through uploading your Dash Enterprise license and airgap bundle.
When the upload is complete, the KOTS Admin Console opens to the Configure Dash Enterprise page.
Now that Dash Enterprise is installed, you’re ready for configuration. The KOTS Admin Console will take you through several configuration options.
On the Configure Dash Enterprise page, do the following:
<img>
Ctrl+C
to disconnect from the Admin Console.You can now access the Admin Console using its sub-domain: https://admin-<your-dash-enterprise-server>
.
Before you can log in to Dash Enterprise at https://<your-dash-enterprise-server>
, you’ll need to create a Dash Enterprise user in Keycloak. Keycloak is the identity and access management solution for Dash Enterprise.
In this step, you’ll retrieve the Keycloak password that is stored as a secret in your cluster and save it according to your organization’s best practices.
To obtain and store the Keycloak password:
sh
kubectl get secret keycloak-secrets -n plotly-system -o jsonpath='{.data.KEYCLOAK_PASSWORD}' | base64 -d && echo
Note about recovering the Keycloak password: Changing this password requires Plotly support. Do not rotate it without contacting us.
In this step, you’ll log in to Keycloak using the stored credentials and create a new user with the admin
role. The admin
role grants access to the Admin section of the Dash Enterprise App Manager, which you’ll use to configure system limits
in a later step. Learn more about the admin role.
To access Keycloak and create your admin user:
https://auth-<your-dash-enterprise-server>
<img>
Make sure Dash is selected in the realm list in the top left corner.
Select Users > Add User.
admin
role:admin
; then select Add selected. Note that if you intend on deploying Dash apps, you’ll also need the licensed_user
role, and assigning this role consumes a license seat.To log into Dash Enterprise with this user, go to https://<your-dash-enterprise-server>
and enter the credentials that you saved in Keycloak. Dash Enterprise opens to the Portal. Go to the App Manager by selecting Apps > App Manager.
<img>
In this step, you’ll safeguard Dash Enterprise against usage that would cause the Kubernetes cluster to exceed the resources it can support. Specifically, you’ll add limits to the amount of pods and volumes (PVC) that can exist, temporarily preventing Dash app developers from performing actions that would create more pods and volumes on the cluster when the limit is reached. To do so, you’ll use the System Limits setting in the Admin section of the App Manager. To learn how to calculate and set limits that are appropriate for your cluster, go to Pod and Volume Limits.
In order to upgrade Dash Enterprise, you’ll need a VM with internet access from which to run Plotly-provided, kubectl
-based scripts. The bootstrap node that you provisioned as part of the installation already meets these requirements, so while it is safe to delete it, your organization may want to reuse it for upgrades. If reusing the bootstrap node, be sure to leave your config file on it (upgrade scripts will source it) and, if applicable, keep the outbound rule for dl.plotly.com
.
If you’re deleting the bootstrap node, keep a copy of your config file that you can move to a new bootstrap node when performing upgrades, and remember to allow communication to dl.plotly.com
on it.