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.
Installing Dash Enterprise is an automated process. You’ll run a script on the VM that creates a Kubernetes cluster using kURL and installs Dash Enterprise on it.
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.
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.
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.
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.
TLS/SSL certificates: By default, a TLS certificate is generated for you automatically. This automatically generated certificate works as follows:
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.
Important: 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.
Contact our Customer Success team to get started. We’ll ask you the base domain you want for your Dash Enterprise instance (it must be an FQDN), as well as other questions for support purposes.
Important note about your base domain: The base domain that you select for your Dash Enterprise instance can be changed later, but changing it requires support from Plotly. We recommend being certain of the base domain that you want to use before beginning your installation.
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.
In this step, you’ll move the files that are required for installation to the VM that you’ve provisioned. One way to do this is to use secure copy protocol (SCP).
To transfer the files from your workstation to your VM using SCP:
Ensure you have read-only access to the SSH private key (note this command has no output):
sh
chmod 0400 /path/to/private/key
where /path/to/private/key
is the path to the SSH private key.
Transfer the files to your VM’s home directory:
sh
scp -i /path/to/private/key path/to/installation/script path/to/config/file path/to/root/ca <username>@<server-ip>:~
where:
* /path/to/private/key
is the path to the SSH private key
* 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/root/ca
is the path to your internal root CA certificate, if using
* <username>
is the username of your VM
* <server-ip>
is the IP address you are using.
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 VM.
Don’t forget that to SSH into the VM in the future, you’ll need to append the new SSH port to the ssh
command (for example, -p 2222
).
To install Dash Enterprise:
If you aren’t already, SSH into your VM:
sh
ssh -i /path/to/private/key <username>@<server-ip> -p 2222
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.
In the home directory of your VM, run the installation script:
sudo bash install_de_single_server.sh
(RHEL only) When prompted to disable firewalld
, press y
to confirm (Dash Enterprise does not support firewalld
).
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
.
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:
http://<server-ip>:8800
, where <server-ip>
is the IP address you are using.ADMIN_PASSWORD
in Defining Variables in the Script; then select Log in. You are prompted to upload your license.<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: Dash Enterprise does not currently support rotating this password. Keep this password as is to avoid anomalous behavior.
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.