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 5 runs on Kubernetes, an open-source system that automates application lifecycles. When you install Dash Enterprise on a single server, you work with a Kubernetes cluster that consists of a single node.
Installing Dash Enterprise is an automated process. You’ll run a script on your bare metal server that creates the 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: Dash Enterprise interacts with the Kubernetes API to organize 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.
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-----
Self-signed certificates, internally signed certificates, and using multiple certificates are not supported. If you obtained your certificate 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.
You’ll upload the full certificate chain and unencrypted private key during the configuration, and they will be used to terminate TLS/SSL.
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 the base domain you want for your Dash Enterprise instance (it must be an FQDN), as well as other questions for support purposes.
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.restore.sh
, containing commands for installing supporting software on a fresh server. This script is provided in the event that you back up Dash Enterprise and need to restore your data. It is not used for the installation.Unzip your Installation Plan and open the installation script. 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 downloading the KOTS CLI and runningkubectl kots reset-password plotly-system
.
In this step, you’ll move your Dash Enterprise installation script to your bare metal server. One way to do this is to use secure copy protocol (SCP).
To transfer your installation script to your bare metal server’s home directory using SCP:
sh
scp -i path/to/private/key path/to/installation/script <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, <username>
is the username of your bare metal server, and <server-ip>
is the IP of your bare metal server.
Dash Enterprise expects Dash 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.
This procedure differs based on the operating system of your bare metal server.
The next time you SSH into the server, you’ll need to append the new SSH port to the ssh
command.
To install Dash Enterprise:
If you aren’t already, SSH into your bare metal with the new SSH port:
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, <server-ip>
is the IP of your bare metal server, and <new-ssh-port>
is the port you chose to replace 22
.
In the home directory of your bare metal server, run the installation script:
bash install_de_single_server.sh
If you are prompted for the kots
install location by Enter installation path (leave blank for /usr/local/bin)
, press Enter
to accept the default.
If you are prompted to grant write permissions to /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
.
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 uploading your Dash Enterprise license as well as your TLS/SSL certificate and key.
To access the KOTS Admin Console and configure Dash Enterprise:
http://<server-ip>:8800
, where <server-ip>
is the IP of your bare metal server.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
Note about recovering the Keycloak password: If you change this password via the Keycloak interface, it will no longer correspond to what is
stored in your cluster. We recommend keeping it as is so that you can always recover it with thiskubectl get secret
command.
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.