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

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.

This guide describes how to use Amazon Elastic Compute Cloud (EC2) to provision a virtual machine (or EC2 instance) that will act as the server, but you can still follow this guide if you already have an EC2 instance ready to go.

Installing Dash Enterprise is an automated process. You’ll run a script on the EC2 instance that creates the Kubernetes cluster using kURL and installs Dash Enterprise on it.

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.

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.

Prerequisites

Here’s what you’ll need before you can start your Dash Enterprise installation:

• A workstation with internet access and a web browser.
• A wildcard or multi-domain TLS/SSL full certificate chain and unencrypted private key obtained from a globally trusted certificate authority (CA). The full certificate chain must be a .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.

• The following AWS resources:
• An AWS account.
• A VPC with a public or private subnet that you’ll use for the EC2 instance.
• If you’ll be using a public subnet and you want to reach your cluster via a public IP, you’ll need to associate an Elastic IP address to the EC2 instance (to prevent the IP address from changing). Learn how to allocate an Elastic IP address if you don’t already have one available.
• The subnet that you want to use has routes to the following domains at minimum:

where <base-domain> is the base domain you chose for Dash Enterprise.

• (If following this guide to provision the EC2 instance) An IAM user that you’ll use to provision the EC2 instance. Learn how to create a new IAM user. The IAM user you choose can be one that you consider a service account, and must have permission to create and manage EC2 instances (as well as associate Elastic IP addresses, if using).

• The following DNS entries:

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 Elastic IP or private IP that you want to use to reach your server.

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 an FQDN), as well as other questions for support purposes.

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 Dash Enterprise license file.
• Your restore script, restore.sh, containing commands for installing supporting software on a fresh EC2 instance. 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.

Defining Variables in the Script

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 running kubectl kots reset-password 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). If you do not need to configure a proxy, leave this blank and skip to Provisioning Your VM.

Provisioning Your VM

In this step, you’ll use the AWS Management Console to provision an EC2 instance.

Already have an EC2 instance ready to go?
You can use an existing EC2 instance and skip to Configuring the SSH Port, as long as your EC2 instance meets these requirements: * Ubuntu 22 as its operating system * 64-bit x86 architecture * Instance type:
* For the Standard offering of Dash Enterprise: c6i.8xlarge (recommended) or a different instance type chosen with our Customer Success team.
* For the Premium offering of Dash Enterprise: m6i.16xlarge. * Disk: 1024 GiB storage size, gp3 volume type, and 10000 IOPS. * Ports 443, 80, 22, and 8800 are open. * A port of your choosing is open that will replace 22 to SSH into the instance (cannot be any of the ports above). * Its VPC meets the prerequisites. * An associated Elastic IP address, if using.

To provision your EC2 instance:

1. In the AWS Management Console, go to the EC2 service.
2. Select Launch instance.

<img>

3. In Name, enter a name for your EC2 instance.
4. Configure the Application and OS Images:
5. Under Quick Start, select Ubuntu.
6. For Amazon Machine Image (AMI), select Ubuntu Server 22.04 LTS (HVM), SSD Volume Type.

7. For Architecture, use the default 64-bit (x86).

8. For Instance type, select one of the following:
   * For the Standard offering of Dash Enterprise: c6i.8xlarge (recommended) or a different instance type chosen with our Customer Success team.
   * For the Premium offering of Dash Enterprise: m6i.16xlarge.

9. Create a new SSH key pair that you’ll use to SSH into this EC2 instance:
10. In Key pair (login), select Create new key pair.
11. In Key pair name, enter a name for your key pair. We recommend dash-enterprise_key to more easily follow commands that reference the private key later in this guide.
12. Use the default RSA key pair type and .pem format.

13. Select Create key pair.

14. Configure the network settings:

15. In Network settings, select Edit.
16. Select the VPC and Subnet that you want to use. Make sure that the VPC meets the prerequisites.
17. For Firewall (security group), select Create security group.
18. Enter a Security group name and Description.

19. Add the following five firewall rules:

    • Type: ssh, Source type: My IP
    • Type: HTTP, Source type: Anywhere
    • Type: HTTPS, Source type: Anywhere
    • Type: Custom TCP, Source type: My IP, Port range: 8800 (required to port-forward the KOTS Admin Console)

    • Type: Custom TCP, Port range of your choosing that will replace 22 to SSH into this instance (cannot be any of the ports used in the above rules). In the example below, we use 2222.

      <img>

20. Configure the storage:

21. In Configure storage, select Advanced.
22. Expand Volume 1.
23. In Size (GiB), enter 1024.
24. For Volume type, select General purpose SSD (gp3).
25. In IOPS, enter 10000.

26. In Throughput, enter 500.

    <img>

27. Use the default settings for everything else or adjust them to your preference.

28. Select Launch instance.

29. (If using an Elastic IP address) Once the EC2 instance is ready, associate your Elastic IP address:

    1. In the navigation pane, go to Elastic IPs.

    <img>

    2. Select the Elastic IP address you want to use; then select Actions > Associate Elastic IP address.

    <img>

    3. Set Resource type to Instance.
    4. In Instance, select your EC2 instance.
    5. Select Associate.

Moving Files to Your VM

In this step, you’ll move your Dash Enterprise installation script to the EC2 instance you’ve provisioned. One way to do this is to use secure copy protocol (SCP).

To transfer your installation script from your workstation to your EC2 instance using SCP:

1. Move the downloaded SSH private key to your .ssh directory:
   sh mv /path/to/downloaded/private/key ~/.ssh/
   where /path/to/downloaded/private/key is the path to the current location of the private key.

2. Ensure you have read-only access to the private key (note this command has no output):
   sh chmod 0400 ~/.ssh/dash-enterprise_key.pem
   changing dash-enterprise_key.pem if your key has a different name.

3. Transfer your installation script to your EC2 instance’s home directory:
   scp -i ~/.ssh/dash-enterprise_key.pem path/to/installation/script ubuntu@<server-ip>:~
   where path/to/installation/script is the path to install_de_single_server.sh in your Installation Plan and <server-ip> is the Elastic IP or private IP you are using. Change dash-enterprise_key.pem if your private key has a different name.

Configuring the SSH Port

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.

To configure the SSH port:

1. SSH into the EC2 instance:
   sh ssh -i ~/.ssh/dash-enterprisep_key.pem ubuntu@<server-ip>
   where <server-ip> is the Elastic IP or private IP you are using. Change dash-enterprise_key.pem if your private key has a different name.

2. Open the sshd_config file:
   sh sudo vi /etc/ssh/sshd_config

3. Find the line that says #Port 22; then remove the # and change the port number to the new SSH port that you chose earlier. For example, Port 2222.

4. Save and exit:
   sh :wq

5. Reload and restart sshd:
   sh sudo systemctl daemon-reload sudo systemctl restart sshd

The next time you SSH into the instance, you’ll need to append the new SSH port to the ssh command.

Installation

To install Dash Enterprise:

1. If you aren’t already, SSH into your EC2 instance with the new SSH port:
   sh ssh -i ~/.ssh/dash-enterprise_key.pem ubuntu@<server-ip> -p 2222
   where <server-ip> is the Elastic IP or private IP you are using. Change dash-enterprise_key.pem if your private key has a different name, and 2222 if you chose a different port.

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

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

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

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 uploading your Dash Enterprise license as well as your TLS/SSL certificate and key.

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 Elastic IP or private IP 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. Upload your TLS/SSL certificate and key.
5. Select Continue. The Admin Console runs preflight checks, which can take up to a few minutes.
6. Wait for the preflight checks to complete. If the results are all successful, select Continue. If you encounter an error, contact Customer Success.
   The Admin Console opens to the dashboard, where the status of the system is displayed.
7. Wait for the status to change to Ready. This can take up to a few minutes.

<img>

8. On your EC2 instance, 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 EC2 instance, 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

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 this kubectl get secret command.

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 Save. 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 Mappings.
    2. In Client Roles, select dash.
    3. In Available Roles, select 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>

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