Install Dash Enterprise on a Virtual Machine via a Cloud Marketplace

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) and you have purchased Dash Enterprise from an online marketplace.

Dash Enterprise is available for purchase via the Amazon Web Services (AWS) Marketplace. Other marketplaces may be supported in the future.

About Dash Enterprise: Use Cases

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.

Cost Model and Billable Services

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.

About the Installation

Installing Dash Enterprise is an automated process: You’ll use the Amazon Elastic Compute Cloud (EC2) service in the AWS Management Console to provision a virtual machine (VM). Then, you’ll run a script on your VM 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.

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.

Deployed Resources

A Dash Enterprise installation completed with this guide comprises the following AWS resources:

Note: Dash Enterprise does not depend on AWS Instance Metadata Service Version 1.

An architecture diagram appears below:

<img>

All data collected by Dash Enterprise is stored on EBS volumes or S3 buckets and is encrypted at rest. Dash Enterprise does not provide any encryption-related options.

Your Dash Enterprise installation will be subject to your AWS account service quotas. You can read about monitoring these limits in the AWS documentation here.

Before You Install

Here are some important notices and details about supported configurations before you get started.

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.

Prerequisites

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

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.

Domain/Port Purpose When I/O
kurl.sh 443 Download kURL Installation Outbound
s3.kurl.sh 443 Download kURL Installation Outbound
prod-registry-k8s-io-&lt;region&gt;.s3.dualstack.&lt;region&gt;.amazonaws.com 443 Download Ingress NGINX Controller image from Amazon S3 Installation Outbound
registry.k8s.io 443 Download kubectl Installation Outbound
pkg-containers.githubusercontent.com 443 Download Containerd Installation Outbound
api.github.com 443 Get latest versions of Dash Enterprise Workspaces Runtime Outbound
replicated.com 443 Retrieve private Dash Enterprise images, validate license Installation, upgrade, license validation Outbound
proxy.replicated.com 443 Retrieve private Dash Enterprise images, validate license Installation, upgrade, license validation Outbound
proxy-auth.replicated.com 443 Retrieve private Dash Enterprise images, validate license Installation, upgrade, license validation Outbound
registry.replicated.com 443 Retrieve private Dash Enterprise images, validate license Installation, upgrade, license validation Outbound
replicated.app 443 Send Dash Enterprise version, license ID, and app ID to Replicated for authentication; retrieve Dash Enterprise YAML files and metadata Installation Outbound
gcr.io 443 Download Docker image for Kpack Installation, upgrade Outbound
k8s.gcr.io 443 Download Docker image for Kpack Installation, upgrade Outbound
ghcr.io 443 Download Docker image for Harbor Installation, upgrade Outbound
auth.docker.io 443 Download Weave and Docker image for Kpack Installation, upgrade Outbound
registry-1.docker.io 443 Download Weave and Docker image for Kpack Installation, upgrade Outbound
production.cloudflare.docker.com 443 Download Weave and Docker image for Kpack Installation, upgrade Outbound
quay.io 443 Download Docker images for Fluent Bit, Reloader, and Cert Manager. Get latest versions of Dash Enterprise Workspaces. Installation, upgrade, runtime Outbound
cdn.quay.io 443 Download Docker images for Fluent Bit, Reloader, and Cert Manager Installation, upgrade Outbound
cdn01.quay.io 443 Download Docker images for Fluent Bit, Reloader, and Cert Manager Installation, upgrade Outbound
cdn02.quay.io 443 Download Docker images for Fluent Bit, Reloader, and Cert Manager Installation, upgrade Outbound
cdn03.quay.io 443 Download Docker images for Fluent Bit, Reloader, and Cert Manager Installation, upgrade Outbound
storage.googleapis.com 443 Download static assets Installation, upgrade Outbound
*.pkg.dev 443 Download dependencies for Kpack Installation, upgrade Outbound
acme-v02.api.letsencrypt.org 443 (if using an automatically generated certificate) Obtain and renew the Let’s Encrypt certificate Installation, Runtime Outbound
docs-de5.plot.ly 443 Access documentation Runtime Outbound
packages.plot.ly 443 Access Dash Enterprise libraries like Dash Design Kit when building app images Runtime Outbound
licensing.plotly.host 443 Licensing and support Runtime Outbound
dl.plotly.com 443 Download the Dash Enterprise upgrade tool Upgrade Outbound
selfserve.plot.ly 443 Connect to the Plotly control plane during Dash Enterprise upgrades Upgrade Outbound
subnet.min.io 443 Access the object store for KOTS Runtime Outbound
pypi.org 443 Download public Python packages when building app images Runtime Outbound
buildpacks.cloudfoundry.org 443 Download Python binaries Runtime Outbound
files.pythonhosted.org 443 Download setuptools Runtime Outbound
anaconda.org 443 Download Conda packages when building app images Runtime Outbound
*.ubuntu.com 443 and 80 Download APT packages when building app images Runtime Outbound
*.launchpad.net 443 Download APT packages when building app images Runtime Outbound
*.&lt;base-domain&gt; 443 Access Harbor (registry) when building app images Runtime Outbound

where &lt;region&gt; is the AWS region of your VM and &lt;base-domain&gt; is the base domain you chose for Dash Enterprise.

Preparing Your Installation

Contact our Customer Success team to get started. We’ll ask you:

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:

Provisioning Your VM

In this step, you’ll use the EC2 service along with the Amazon Machine Image that you received from AWS Marketplace to provision a VM running Ubuntu 22.04.

To provision your VM:

  1. In the AWS Management Console, go to Marketplace > Manage Subscriptions and select Plotly Dash Enterprise 5.
  2. Choose your desired region, then select Launch new instance, then Continue to launch through EC2.

<img>

  1. In Name, enter a name for your EC2 instance.

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

  3. Create a new SSH key pair that you’ll use to SSH into this EC2 instance:
  4. In Key pair (login), select Create new key pair.
  5. In Key pair name, enter a name for your key pair.
  6. Use the default RSA key pair type and .pem format.
  7. Select Create key pair.

  8. Configure the network settings:

  9. In Network settings, select Edit.
  10. Select the VPC and Subnet that you want to use. Make sure that the VPC meets the prerequisites.
  11. For Firewall (security group), select Create security group.
  12. Enter a Security group name and Description.
  13. 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, Source type: My IP, 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). For example, 2222. If you plan to customize the Git SSH port when configuring Dash Enterprise, then this is not needed.

      <img>

  14. Configure the storage:

  15. In Configure storage, select Advanced.
  16. Expand Volume 1.
  17. In Size (GiB), enter 1024.
  18. For Volume type, select General purpose SSD (gp3).
  19. In IOPS, enter 10000.
  20. In Throughput, enter 500.

    <img>

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

  22. Select Launch instance.
  23. (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>

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

    <img>

    1. Set Resource type to Instance.
    2. In Instance, select your EC2 instance.
    3. Select Associate.

Defining Variables in the Script

Unzip your Installation Plan and open the config file. Edit the following variable values:

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 running enter_bootstrap_pod.sh on your server and then kubectl kots reset-password -n plotly-system.

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:

Moving Files to Your VM

Move the following files to the home directory of your VM: * Your installation script, install_de_single_server.sh * Your config file, config.local.sh * The script for entering the bootstrap pod, enter_bootstrap_pod.sh * Your internal root CA certificate, if using

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/bootstrap/pod/script path/to/root/ca ubuntu@&lt;server-ip&gt;:~
    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/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
    * &lt;server-ip&gt; 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.

To configure the SSH port:

  1. SSH into the VM:
    sh ssh -i /path/to/private/key ubuntu@&lt;server-ip&gt;
    where /path/to/private/key is the path to the private key and &lt;server-ip&gt; is the IP address you are using.

  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.

  4. Save and exit:
    sh :wq

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

  6. Important: Go back to your VM networking settings and change the source for the port 22 rule to the IP addresses of users who will deploying apps.

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

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:

  1. If you aren’t already, SSH into your VM:
    sh ssh -i /path/to/private/key &lt;username&gt;@&lt;server-ip&gt; -p 2222
    where /path/to/private/key is the path to the private key, &lt;username&gt; is the username of your VM, and &lt;server-ip&gt; 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

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://&lt;server-ip&gt;:8800, where &lt;server-ip&gt; 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 Hostname Settings, make sure your Dash Enterprise hostname is entered. If it isn’t, enter it, making sure it corresponds to the value for DE_HOSTNAME in your config file.
  5. 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.
  6. 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.
  7. If you plan to set up Dash Enterprise authentication with an external SAML, OIDC, or LDAP server, and this server uses a self-signed certificate, configure Dash Enterprise to trust the server:
  8. Under Auth Settings, select Upload Self-signed / Internal Public CA Certificate. A file upload field appears.
  9. Drag or browse to the certificate that will establish trust. This certificate has the following requirements:

    • It must be a DER or base64-encoded file.
    • The Common Name (Server Name) in the certificate must be set to the fully qualified domain name (FQDN) that Dash Enterprise will use to reach your server.

    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.
    8. 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.
    9. Select Continue. The Admin Console runs preflight checks, which can take up to a few minutes.
    10. 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>

    1. Optional: Select Test connection to check the connection to your private container registry.
    2. Select Save changes.
    3. Go to the Dashboard.
    4. Select Deploy.
  10. Wait for the status in the dashboard to change to Ready. This can take up to a few minutes.

<img>

  1. 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-&lt;your-dash-enterprise-server&gt;.

Accessing Dash Enterprise

Before you can log in to Dash Enterprise at https://&lt;your-dash-enterprise-server&gt;, 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: Changing this password requires Plotly support. Do not rotate it without contacting us.

  1. Copy the password.
  2. 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-&lt;your-dash-enterprise-server&gt;
  2. Select Administration Console.
  3. Enter the Keycloak credentials that you obtained and stored.

<img>

  1. Select Sign In.
  2. Make sure dash is selected in the realm list in the top left corner.

    Dash realm

  3. Select Users > Add User.

  4. In Username, enter the username you want to use.
  5. Select Create. Additional settings become available.
  6. Go to Credentials.
  7. In Password and Password Confirmation, enter the password you want to use.
  8. Select Set Password; then set password again to confirm.
  9. 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://&lt;your-dash-enterprise-server&gt; 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>

Health Check and Handling Fault Conditions

Dash Enterprise may become unavailable if you experience an infrastructure disruption or exceed your cloud provider’s service limits (if applicable).

We recommend you take regular backups of your Dash Enterprise instance. In a situation where the VM experiences a problem, you can restore from the most recent backup to recover Dash Enterprise.

You can monitor system health and status by logging in to the KOTS Admin Console at https://admin-&lt;your-dash-enterprise-server&gt;.

Getting Support

See here for information on how to get support for Dash Enterprise.

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.