Install Dash Enterprise on a Bare Metal Server - Airgapped

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 use a bootstrap node to run a Plotly-provided script that creates a Kubernetes cluster using kURL and installs Dash Enterprise on your bare metal server. A bootstrap node is a machine whose purpose is to run the script. If you choose a short-lived machine for this task, you can stop or decommission it after the installation.

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

In order for Dash app developers to use an airgapped Dash Enterprise instance, their apps need to fetch Python package dependencies from an internal index. (If there is no internal index available, developers need to place Python packages individually in their app’s files, which is not recommended for apps that require many packages because it involves additionally managing those packages’ dependencies).

Before committing to an airgapped Dash Enterprise installation, make sure your organization can provide an internal index. Dash Enterprise requires that the index have a TLS/SSL certificate from a globally trusted certificate authority (CA). A common strategy is to create a mirror of pypi.org.

Important: Apps deployed to Dash Enterprise use Python 3.8.16. Be sure that the packages in your internal index are compatible with this version. When Dash Enterprise is airgapped, it is not possible for app developers to change the Python version that their apps use.

Similarly, if Dash app developers plan to deploy apps that depend on APT packages, you’ll need to prepare a custom APT repository with a TLS/SSL certificate from a globally trusted certificate authority (CA).

Prerequisites

Important: Stopping and restarting the server that Dash Enterprise is installed on (often called parking) is not supported. The server must be left on for Dash Enterprise to remain in a healthy state.

Minimum specifications for the bare metal server change depending on which offering of Dash Enterprise your organization has purchased.

• A machine that will serve as your bootstrap node (can be a laptop or a VM). This machine has the following requirements:
• The same operating system as your Dash Enterprise server
• 64-bit x86 architecture
• 1 CPU core or 2 vCPU
• At least 4 GB memory
• At least 20 GB of free disk space
• As little software installed on it as possible
• Internet access
• Network access to the bare metal server
• Network access to the private container registry
• Contains the SSH private key
• The host network or VPC subnet has routes to the following domains at minimum:

• A workstation with internet access, a web browser, and 20 GB of free disk space (only required if your bootstrap node does not have a web browser)

• A wildcard or multi-domain TLS/SSL full certificate chain and unencrypted private key. 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-----
  The root certificate can be issued by an external/globally-trusted CA or by a CA internal to your organization. Using multiple certificates or self-signed certificates are not supported.

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.

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 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 IP address of your bare metal 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 a fully qualified domain name (FQDN).

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.

• Whether your environment has any requirements (if your environment requires advanced configuration, an additional Support and Services Engagement may be required).
• 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 this information, we’ll send you a tailor-made installation script as well as a link and password to a download portal from which you’ll need to download airgap bundles. 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_ss_airgap.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.

Defining Variables in the Scripts

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

• HOST_INTERNAL_REGISTRY: The URL to the private container registry you are using for Dash Enterprise images, including the desired namespace.
• HOST_INTERNAL_REGISTRY_USER: The username for the account you’ll use to pull and push images to your private container registry.
• HOST_INTERNAL_REGISTRY_PASSWORD: The password for the account you’ll use to pull and push images to your private container registry.
• AUTH_REGISTRY_PULLS: 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: If AUTH_REGISTRY_PULLS is set to true, provide the URL to the private container registry without namespaces. Otherwise, leave empty.
• INSTANCE_SSH_TARGET: The IP address of your bare metal server (used by the installation script to SSH into the server).
• INSTANCE_SSH_PORT: The port that you want to use for SSH on your server, which corresponds to the rule that you optionally added when you provisioned your server. This will be used by the installation script to remap the Linux OpenSSH daemon (sshd) on your server to your chosen port. Remapping the sshd is required in order for it to not conflict with the Git SSH port. If you plan to customize the Git SSH port when configuring Dash Enterprise, then there will be no conflict, and you can set INSTANCE_SSH_PORT to 22.
• INSTANCE_SSH_USERNAME: The username for the bare metal server (used by the installation script to SSH into the server).
• INSTANCE_SSH_IDENTITY: The path to the SSH private key on your bootstrap node (used by the installation script to SSH into the server).
• SKIP_PUSH_IMAGES: Set to true if you have retrieved the Dash Enterprise images into your private container registry before the installation. Otherwise, leave false.
• SKIP_REGISTRY_CHECK: Set to true if you have retrieved the Dash Enterprise images into your private container registry before the installation. Otherwise, leave false.
• KURL_PRIVATE_IP: If your bare metal server has more than one network interface, specify the IP address for kURL to use when creating the Kubernetes cluster. If your server 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 bootstrap node. If using, you’ll move the internal root CA certificate to the home directory of the bootstrap node, so set INTERNAL_CA_CERTIFICATE to the corresponding path, taking care to include the full name of the certificate, including its .crt extension.

Downloading Your Airgap Bundle

In this step, you’ll download the airgap bundle required to install Dash Enterprise. Note that the Dash Enterprise airgap bundle is approximately 15 GB.

To download the airgap bundle:

1. On your bootstrap node or workstation (whichever has a web browser), use the link and password provided by our Customer Success team to go to the download portal.
2. In the left sidebar, make sure Bring my own cluster is selected.
3. Under dash-enterprise Airgap Bundle, select Download airgap bundle.

Installation and Configuration

Creating the Cluster and Port-Forwarding the KOTS Admin Console

In this step, you’ll run the installation script from your bootstrap node. This script does the following:

• SSHes into the bare metal server using port 22, then remaps the SSH port to the port you specified in INSTANCE_SSH_PORT.
• Downloads kURL and moves it to your bare metal server to create the Kubernetes cluster.
• Creates the plotly-system namespace, in which the core system components of Dash Enterprise will be installed.
• Generates a kubeconfig file (~/.kube/config) to run kubectl commands against the Kubernetes cluster.
• Authenticates your user to your private container registry for image pulls and pushes.
• Downloads the KOTS airgap bundle.
• Installs the KOTS CLI as well as the KOTS Admin Console using the KOTS airgap bundle, and then port-forwards the Admin Console so that you can use it to install Dash Enterprise.

To create the cluster and port-forward the KOTS Admin Console:

1. Move the installation script, config file, and internal root CA certificate (if using) to the home directory of your bootstrap node if they aren’t there already.
2. In the home directory of your bootstrap node, run the installation script:

sudo bash install_de_ss_airgap.sh

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

5. You can now change port 22 to add only the IP addresses of users who will be deploying Dash apps to Dash Enterprise. Alternatively, if you plan to customize the Git SSH port, then you can close or restrict port 22.

Uploading the License and Airgap Bundle

Now that your cluster is created, you’re ready to install Dash Enterprise on it. The KOTS Admin Console will take you through uploading your Dash Enterprise license and airgap bundle.

Note: If using a bootstrap node with a web browser for this step and the following step, you’ll need to move your Dash Enterprise license file, Dash Enterprise airgap bundle, and TLS/SSL certificate and key to your bootstrap node.

To access the KOTS Admin Console and install Dash Enterprise:

1. On a machine with a web browser, go to the port-forwarded KOTS Admin Console:
   * If using a workstation, go to http://<bootstrap-ip>:8800, where <bootstrap-ip> is the external IP address of your bootstrap node.
   * If using a bootstrap node with a web browser, go to http://localhost:8800.
2. Enter the password that you set for ADMIN_PASSWORD in Defining Variables in the Scripts; 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 Install in airgapped environment page, where your private container registry information is automatically entered.
4. In the area labelled “Drag your airgap bundle here or choose a bundle to upload,” drag or browse to the Dash Enterprise .airgap file you downloaded earlier.
5. If you have not retrieved the Dash Enterprise images into your private container registry before the installation (SKIP_PUSH_IMAGES and SKIP_REGISTRY_CHECK are false in your config file), clear the Disable Pushing Images to Registry checkbox. (Note that this setting will be saved and applied when you upgrade Dash Enterprise. Change it in the Admin Console registry settings if you don’t want to keep this workflow for Dash Enterprise upgrades).
6. Select Upload airgap bundle. The upload can take several minutes.

When the upload is complete, the KOTS Admin Console opens to the Configure Dash Enterprise page.

Uploading the Certificate and Running Preflight Checks

Now that Dash Enterprise is installed, you’re ready for configuration. The KOTS Admin Console will take you through uploading your TLS/SSL certificate and running preflight checks.

On the Configure Dash Enterprise page, do the following:

1. In TLS Settings, make sure that Upload TLS Certificate and Key is selected, and then upload your TLS/SSL certificate and key.
2. 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.
3. In PIP_EXTRA_INDEX_URL, enter the URL of your organization’s private Python package index (you can also configure it later). This will cause all apps and workspaces on Dash Enterprise to be able to fetch dependencies from this index.
4. Select Continue. The Admin Console runs preflight checks, which can take up to a few minutes.
5. 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.
6. Wait for the status to change to Ready. This can take up to a few minutes.

<img>

6. On your bootstrap node, 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 bootstrap node, 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 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 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.

Post-Install Bootstrap Node Considerations

In order to upgrade Dash Enterprise, you’ll need a laptop or VM with internet access from which to run Plotly-provided, kubectl-based scripts. The bootstrap node that you used as part of the installation already meets these requirements, so while it is safe to delete or decommission it, your organization may want to reuse it for upgrades. If reusing the bootstrap node, be sure to leave your config file on it, as upgrade scripts will source it.

If you’re deleting or decommissioning the bootstrap node, keep a copy of your config file that you can move to a new machine when performing upgrades.