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’ll run a script on your bare metal server that creates a Kubernetes cluster using kURL and installs Dash Enterprise on it.
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.
You can configure Dash Enterprise to use an HTTP/HTTPS proxy (address like http://my.proxy.url:port
) that is already present in your environment. Secure HTTP proxies (addresses like https://my.proxy.url:port
) are not 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.
Changing the VM IP: Changing the internal and/or public IP of the server after installation is not supported.
HTTP/HTTPS proxies: You can configure Dash Enterprise to use an HTTP/HTTPS proxy (address like http://my.proxy.url:port
) that is already present in your environment. Secure HTTP proxies (addresses like https://my.proxy.url:port
) are not supported. To configure a proxy, follow the instructions in this guide. The proxy must support websocket connections.
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 server, make sure that it supports websocket connections.
TLS/SSL certificates: You’ll need to upload a TLS/SSL certificate unless your server is in a public network. Be sure to read the certificate requirements in the Prerequisites carefully.
If your server is in a public network, a TLS certificate is generated for you automatically by default. This automatically generated certificate works as follows:
* The TLS certificate is issued by Let’s Encrypt, a globally-trusted certificate authority (CA), so it is already in the root of trust stores used by major browsers, operating systems, and applications. Internet traffic is authenticated and encrypted with no additional configuration.
* Let’s Encrypt uses the Automatic Certificate Management Environment (ACME) protocol for automated management of the certificate. The certificate is automatically renewed every 90 days.
* Cert Manager, a Kubernetes-native component that is installed with Dash Enterprise, takes care of creating the required ACME client.
* You cannot view or download the automatically generated certificate.
* It is not compatible with private container registries.
If an automatically generated certificate is not appropriate for your organization, you can choose to upload a TLS/SSL certificate. This guide can help you do so. Be sure to read the certificate requirements in the Prerequisites carefully.
If configuring your installation to use a private container registry, you must upload a TLS/SSL certificate; the automatically generated certificate is not supported.
Minimum specifications for the bare metal server change depending on which offering of Dash Enterprise your organization has purchased.
.pem
file in the following format:txt
-----BEGIN CERTIFICATE-----
<Your>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Your>
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
<Your>
-----END CERTIFICATE-----
The root certificate can be issued by an external/globally-trusted CA or by a CA that is internal to your organization.
If you obtained your certificate chain as multiple files, you need to combine them into a single .pem
file. You can do this with cat server.pem intermediate.pem trustedroot.pem > fullchain.pem
on Linux or copy server.pem+intermediate.pem+trustedroot.pem fullchain.pem
on Windows, replacing the file names if yours are different. Using multiple certificates or self-signed certificates are not supported.
You’ll upload the full certificate chain and unencrypted private key during the configuration, and they will be used to terminate TLS/SSL.
Artifactory
The following DNS entries:
Name | Type | Value |
---|---|---|
<base-domain> |
A record | <server-ip> |
api-<base-domain> |
CNAME | <base-domain> |
ws-<base-domain> |
CNAME | <base-domain> |
git-<base-domain> |
CNAME | <base-domain> |
registry-<base-domain> |
CNAME | <base-domain> |
auth-<base-domain> |
CNAME | <base-domain> |
admin-<base-domain> |
CNAME | <base-domain> |
where <base-domain>
is a fully qualified domain name (FQDN) that you want to use as the base domain for your Dash Enterprise instance and <server-ip>
is the IP address of your bare metal server.
Contact our Customer Success team to get started. We’ll ask you:
When we have all the information we need, we’ll send you a zipped folder called your Installation Plan. 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_single_server.sh
, which creates the Kubernetes cluster and installs Dash Enterprise as well as supporting software.config.local.sh
, which contains variables used by the installation script. You’ll define some of these variables as part of the install preparation.enter_bootstrap_pod.sh
, which is intended for post-install operations. The bootstrap pod is where key tools will be located after the installation.sha256sums.txt
, provided for support purposes.Unzip your Installation Plan and open the config file. At the top, 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 runningenter_bootstrap_pod.sh
on your server and thenkubectl kots reset-password -n plotly-system
.
HTTP_PROXY
(optional): Your HTTP/HTTPS proxy address. The address format is similar to http://user:pw@proxy.url:port
(addresses beginning with https
are not supported). The proxy must support websocket connections. If you do not need to configure a proxy, leave this blank.HOST_INTERNAL_REGISTRY
(optional): The hostname of the private container registry you are using for Dash Enterprise images, including the desired namespace. Must not include a trailing slash. If using a private container registry, you must also define the following six variables.HOST_INTERNAL_REGISTRY_USER
(optional): The username for the account you’ll use to pull and push images to your private container registry.HOST_INTERNAL_REGISTRY_PASSWORD
(optional): The password for the account you’ll use to pull and push images to your private container registry.AUTH_REGISTRY_PULLS
(optional): 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
(optional): If AUTH_REGISTRY_PULLS
is set to true
, provide the hostname of the private container registry without namespaces. Otherwise, leave empty.SKIP_PUSH_IMAGES
(optional): Leave false
.SKIP_REGISTRY_CHECK
(optional): Leave false
.INSTALL_ISTIO
: Leave false
unless instructed to modify this (and allowing access to istio.io
over 443
) by our Customer Success team.KURL_PRIVATE_IP
: If your bare metal 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 name of your internal root CA certificate file, including its .crt
extension.Move the following files to the home directory of your bare metal server:
install_de_single_server.sh
config.local.sh
enter_bootstrap_pod.sh
To achieve this using secure copy protocol (SCP), use:
sh
scp -i path/to/private/key path/to/installation/script path/to/config/file path/to/bootstrap/pod/script path/to/root/ca <username>@<server-ip>:~
where:
* path/to/private/key
is the path to the SSH private key corresponding to the public key you added to your bare metal server
* path/to/installation/script
is the path to install_de_single_server.sh
in your Installation Plan
* path/to/config/file
is the path to config.local.sh
in your Installation Plan
* path/to/bootstrap/pod/script
is the path to enter_bootstrap_pod.sh
in your Installation Plan
* path/to/root/ca
is the path to your internal root CA certificate, if using
* <username>
is the username of your bare metal server
* <server-ip>
is the IP of your bare metal server
By default, Dash Enterprise expects app deployments over SSH to use port 22. In this step, you’ll map the Linux OpenSSH daemon (sshd
) to a different port to free up port 22 for Dash Enterprise.
If you plan to customize the Git SSH port when configuring Dash Enterprise, then you can skip this step.
This procedure differs based on the operating system of your bare metal server.
If SSHing into the server in the future, you’ll need to append the new SSH port to the ssh
command (for example, -p 2222
).
In this step, you’ll run the installation script from your server. This script does the following:
* Installs Kubernetes via kURL.
* Creates the plotly-system
namespace.
* Creates a bootstrap pod, de5-bootstrap
, inside the plotly-system
namespace.
* Authenticates your user to your private container registry, if applicable.
* Generates a kubeconfig file (~/.kube/config
) to run kubectl
commands against the Kubernetes cluster.
* Port-forwards the Admin Console so that you can use it to configure Dash Enterprise.
To install Dash Enterprise:
If you aren’t already, connect to your bare metal server. If you are SSHing, this is:
sh
ssh -i path/to/private/key <username>@<server-ip> -p <new-ssh-port>
where path/to/private/key
is the path to the SSH private key corresponding to the public key you added to your bare metal server, <username>
is the username of your bare metal server, and <server-ip>
is the IP of your bare metal server. Omit -p <new-ssh-port>
if you did not remap the SSH port, or use the appropriate port if you did.
(RHEL 9 only) Install required system packages for RHEL 9:
sh
sudo yum install -y conntrack-tools container-selinux ethtool fio git glibc iproute iptables-nft policycoreutils-python-utils socat util-linux
In the home directory of your bare metal server, run the installation script:
sudo bash install_de_single_server.sh
The script takes several minutes to complete. Continue when you see the message Forwarding from 127.0.0.1:8800 -> 3000
(do not exit yet).
If you exit by mistake, restart the port-forward with
kubectl port-forward -n plotly-system svc/kotsadm 8800:3000
.
Now that your single-node cluster is created and Dash Enterprise is installed on it, you’re ready for configuration. The KOTS Admin Console will take you through several configuration options.
To access the KOTS Admin Console and configure Dash Enterprise:
On your workstation, open an SSH tunnel:
sh
ssh -i /path/to/private/key <username>@<server-ip> -p 2222 -L 8800:localhost:8800
where /path/to/private/key
is the path to the private key, <username>
is the username of your VM, and <server-ip>
is the IP address you are using. Omit -p 2222
if you did not remap the SSH port, or change 2222
if you chose a different port.
On your workstation, go to http://localhost:8800
.
ADMIN_PASSWORD
in Defining Variables in the Script; then select Log in. You are prompted to upload your license.DE_HOSTNAME
in your config file.Drag or browse to the certificate that will establish trust. This certificate has the following requirements:
Depending on how the IdP certificate is signed, and whether there are intermediate certificate authorities (CAs), you may need to use the full certificate chain.
You can upload this certificate later, but Dash Enterprise will be unable to communicate with the server until it can establish trust.
Learn more about which authentication methods are supported.
9. If applicable, in PIP_EXTRA_INDEX_URL, enter the URL of your organization’s private Python package index (recommended when Dash Enterprise does not have network access to PyPI.org). This will cause all apps and workspaces on Dash Enterprise to be able to fetch dependencies from this index.
10. Select Continue. The Admin Console runs preflight checks, which can take up to a few minutes.
11. Wait for the preflight checks to run. Then, do one of the following:
* If you are not using a private container registry: If all the preflight checks are successful, select Deploy. If you encounter an error, contact Customer Success.
* If you are using a private container registry: The preflight checks display a warning message prompting you to configure your private container registry. (If you encounter any other errors, contact Customer Success.) To configure your private container registry:
1. Select the Plotly logo (<img>) in the top left to go to the dashboard (do not select Deploy).
2. Go to Registry Settings.
3. Enter the Hostname, Username, Password, and Registry Namespace for your private container registry.
4. If you have retrieved the Dash Enterprise images into your private container registry, select Disable Pushing Images to Registry. (Note that this setting will be saved and applied when you upgrade Dash Enterprise.)
<img>
Wait for the status to change to Ready. This can take up to a few minutes.
<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
Important: 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:dash
admin”. Note that if you intend on deploying apps, you’ll also need the “dash
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 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.