Install Dash Enterprise on a Virtual Machine

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.

About the Installation

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.

Before You Install

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.

• 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.

• 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 VM, make sure that it supports websocket connections.

• TLS/SSL certificates: By default, if you install Dash Enterprise on a VM belonging to a public subnet, a TLS certificate is generated for you automatically. 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.

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.

• Using a private container registry: If your organization requires that Dash Enterprise be installed from images hosted in a private container registry, you can configure the installation scripts to use this registry when following this guide. Be sure to read the registry requirements in the Prerequisites carefully.

Prerequisites

Preparing Your Installation

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 a fully qualified domain name (FQDN).
• If applicable, whether you want to retrieve the Dash Enterprise images (and third-party images) in your private container registry before the installation (for instance, to perform a security scan).

Obtaining Your Installation Plan

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:

• Your installation script, install_de_single_server.sh, which creates the Kubernetes cluster and installs Dash Enterprise as well as supporting software.
• Your config file, config.local.sh which contains variables used by the scripts. You’ll define some of these variables as part of the install preparation.
• Your Dash Enterprise license file.

Provisioning Your VM

Defining Variables in the Script

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 running kubectl 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 URL to the private container registry you are using for Dash Enterprise images, including the desired namespace. 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 URL to 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 VM has more than one network interface, specify the IP address for kURL to use when creating the Kubernetes cluster. If your VM 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 EC2 instance. If using, you’ll move the internal root CA certificate to the home directory of the EC2 instance in a later step, so set INTERNAL_CA_CERTIFICATE to the corresponding path, taking care to include the full name of the certificate, including its .crt extension.

Moving Files to Your VM

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:

1. 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.

2. 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.

Configuring the SSH Port

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).

Installation

To install Dash Enterprise:

1. 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.

2. In the home directory of your VM, run the installation script:
   sudo bash install_de_single_server.sh

3. (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.

Configuration

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:

1. On your workstation, go to http://<server-ip>:8800, where <server-ip> is the IP address you are using.
2. Enter the password that you set for ADMIN_PASSWORD in Defining Variables in the Script; then select Log in. You are prompted to upload your license.
3. Drag or browse to the license file in your Installation Plan; then select Upload license. The Admin Console opens to the Configure Dash Enterprise page.
4. In TLS Settings, do one of the following:
   * Leave Upload TLS Certificate and Key cleared to let the system generate a certificate (supported if installing in a public subnet only).
   * Select Upload TLS Certificate and Key and then upload your TLS/SSL certificate and key.
5. In Git Settings, review the Git SSH Port. The Git SSH port is set to 22 by default. If you change this port, consider the following carefully:
   * App developers will need to modify their SSH config in order to deploy over SSH from their workstations.
   * You don’t need to open your chosen port to any IPs; it just needs to be available (not bound to any other service).
   * You cannot use ports 80 or 443 for the Git SSH port.
   * After changing the default Git SSH port, you can close or restrict port 22.
6. 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.
7. Select Continue. The Admin Console runs preflight checks, which can take up to a few minutes.

8. 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>

   5. Optional: Select Test connection to check the connection to your private container registry.
   6. Select Saves changes.
   7. Go to the Dashboard.
   8. Select Deploy.

9. Wait for the status in the dashboard to change to Ready. This can take up to a few minutes.

<img>

10. On your VM, press 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>.

Accessing Dash Enterprise

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.

Obtaining and Storing the Keycloak Password

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:

1. On your VM, retrieve the password to Keycloak (this displays the password in plain text):

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.

2. Copy the password.
3. Add the password to your organization’s password manager or other secure storage, along with the username admin. You can share these credentials with other members in your organization who need to access Keycloak.

Creating Your Dash Enterprise Admin User

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:

1. Go to https://auth-<your-dash-enterprise-server>
2. Select Administration Console.
3. Enter the Keycloak credentials that you obtained and stored.

<img>

4. Select Sign In.

5. Make sure dash is selected in the realm list in the top left corner.

   

6. Select Users > Add User.

7. In Username, enter the username you want to use.
8. Select Create. Additional settings become available.
9. Go to Credentials.
10. In Password and Password Confirmation, enter the password you want to use.
11. Select Set Password; then set password again to confirm.
12. Assign the admin role:
    1. Go to Role mapping.
    2. Select Assign role.
    3. Change the filter to Filter by clients.
    4. Find and select the role called “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.
    5. Select Assign.

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>

Setting System Limits

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.