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 use a bootstrap node to run a Plotly-provided script that creates the 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 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: 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.
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. If your organization is instead building its own custom index, here are the Python packages we recommend making available (note that the version numbers were obtained via pip freeze
in May 2023):
Expand list of packages
alembic==1.10.4
amqp==5.1.1
ansi2html==1.8.0
anyio==3.6.2
aplus==0.11.0
argon2-cffi==21.3.0
argon2-cffi-bindings==21.2.0
arrow==1.2.3
asn1crypto==1.5.1
astor==0.8.1
asttokens==2.2.1
attrs==23.1.0
autograd==1.5
autograd-gamma==0.5.0
backcall==0.2.0
beautifulsoup4==4.12.2
billiard==3.6.4.0
blake3==0.3.3
bleach==6.0.0
blinker==1.6.2
boto3==1.26.129
botocore==1.29.129
Brotli==1.0.9
cachetools==5.3.0
celery==5.2.7
certifi==2023.5.7
cffi==1.15.1
chardet==5.1.0
charset-normalizer==3.1.0
click==8.1.3
click-didyoumean==0.3.0
click-plugins==1.1.1
click-repl==0.2.0
cloudpickle==2.2.1
colorcet==3.0.1
comm==0.1.3
contourpy==1.0.7
cryptography==40.0.2
cx-Oracle==8.3.0
cycler==0.11.0
dash==2.9.3
dash-ag-grid==2.0.0
dash-bootstrap-components==1.4.1
dash-core-components==2.0.0
dash-html-components==2.0.0
dash-renderer==1.9.1
dash-table==5.0.0
dask==2023.4.1
databricks-sql-connector==2.5.1
datashader==0.14.4
datashape==0.5.2
debugpy==1.6.7
decorator==5.1.1
defusedxml==0.7.1
diskcache==5.6.1
distributed==2023.4.1
et-xmlfile==1.1.0
executing==1.2.0
fakeredis==1.0.3
fastjsonschema==2.16.3
filelock==3.12.0
Flask==2.2.2
Flask-Compress==1.13
Flask-Cors==3.0.10
flask-request-id==0.1
Flask-SQLAlchemy==2.5.1
fonttools==4.39.3
formulaic==0.6.1
fqdn==1.5.1
frozendict==2.3.8
fsspec==2023.5.0
future==0.18.3
graphlib-backport==1.0.3
greenlet==2.0.2
gunicorn==20.1.0
h5py==3.8.0
humanize==4.6.0
idna==3.4
importlib-metadata==6.6.0
importlib-resources==5.12.0
interface-meta==1.3.0
ipykernel==6.23.0
ipython==8.12.2
ipython-genutils==0.2.0
ipywidgets==8.0.6
isoduration==20.11.0
itsdangerous==2.1.2
jedi==0.18.2
Jinja2==3.1.2
jmespath==1.0.1
joblib==1.2.0
jsonpointer==2.3
jsonschema==4.17.3
jupyter==1.0.0
jupyter-client==8.2.0
jupyter-console==6.6.3
jupyter-core==5.3.0
jupyter-dash==0.4.2
jupyter-events==0.6.3
jupyter-server==2.5.0
jupyter-server-terminals==0.4.4
jupyterlab-pygments==0.2.2
jupyterlab-widgets==3.0.7
jwt==1.3.1
kiwisolver==1.4.4
kombu==5.2.4
lifelines==0.27.7
llvmlite==0.40.0
locket==1.0.0
lorem==0.1.1
lz4==4.3.2
Mako==1.2.4
markdown-it-py==2.2.0
MarkupSafe==2.1.2
matplotlib==3.7.1
matplotlib-inline==0.1.6
mdurl==0.1.2
mistune==2.0.5
msgpack==1.0.5
multipledispatch==0.6.0
nbclassic==1.0.0
nbclient==0.7.4
nbconvert==7.4.0
nbformat==5.8.0
nest-asyncio==1.5.6
nested-lookup==0.2.22
notebook==6.5.4
notebook-shim==0.2.3
numba==0.57.0
numpy==1.24.3
oauthlib==3.2.2
openpyxl==3.1.2
packaging==20.9
pandas==1.5.3
pandocfilters==1.5.0
param==1.13.0
parso==0.8.3
partd==1.4.0
pexpect==4.8.0
pg8000==1.29.4
pickleshare==0.7.5
Pillow==9.5.0
pkgutil-resolve-name==1.3.10
platformdirs==3.5.0
plotly==5.14.1
progressbar2==4.2.0
prometheus-client==0.16.0
prompt-toolkit==3.0.38
psutil==5.9.5
psycopg2-binary==2.9.6
ptyprocess==0.7.0
pure-eval==0.2.2
pyarrow==12.0.0
pycparser==2.21
pyct==0.5.0
pydantic==1.10.7
Pygments==2.15.1
PyJWT==2.6.0
PyMySQL==1.0.3
pyodbc==4.0.39
pyOpenSSL==23.1.1
pyparsing==3.0.9
pyrsistent==0.19.3
python-dateutil==2.8.2
python-dotenv==1.0.0
python-json-logger==2.0.7
python-utils==3.5.2
pytz==2023.3
PyYAML==6.0
pyzmq==25.0.2
qtconsole==5.4.3
QtPy==2.3.1
redis==3.5.3
regex==2023.5.5
requests==2.30.0
retrying==1.3.4
rfc3339-validator==0.1.4
rfc3986-validator==0.1.1
rich==13.3.5
s3transfer==0.6.1
scikit-learn==1.2.2
scipy==1.10.1
scramp==1.4.4
Send2Trash==1.8.2
six==1.16.0
sniffio==1.3.0
sortedcontainers==2.4.0
soupsieve==2.4.1
SQLAlchemy==1.4.48
stack-data==0.6.2
tabulate==0.9.0
tblib==1.7.0
tenacity==8.2.2
terminado==0.17.1
threadpoolctl==3.1.0
thrift==0.16.0
tinycss2==1.2.1
toolz==0.12.0
tornado==6.3.1
traitlets==5.9.0
typing-extensions==4.5.0
uri-template==1.2.0
urllib3==1.26.15
vaex-core==4.16.1
vaex-hdf5==0.12.3
vine==5.0.0
wcwidth==0.2.6
webcolors==1.13
webencodings==0.5.1
websocket-client==1.5.1
Werkzeug==2.2.2
widgetsnbextension==4.0.7
wrapt==1.15.0
wsgi-request-id==0.2
xarray==2022.9.0
zict==3.0.0
zipp==3.15.0
Important: Apps deployed to Dash Enterprise use Python 3.8.12, so be sure that the packages in your internal index are compatible with this version. When Dash Enterprise is airgapped, it is not possible for Dash 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).
Minimum specifications for the bare metal server change depending on which offering of Dash Enterprise your organization has purchased.
Domain/Port | Purpose | When | I/O |
---|---|---|---|
*.kurl.sh 443 |
Download kURL | Installation | Outbound |
*.docker.com 443 |
Download Docker | Installation | Outbound |
dl.k8s.io 443 |
Download kubectl |
Installation | Outbound |
storage.googleapis.com 443 |
Download kubectl |
Installation | Outbound |
github.com 443 |
Download Cert Manager | Installation | Outbound |
*.githubusercontent.com 443 |
Download ImageSwap | Installation | Outbound |
*.istio.io 443 |
Download Istio | Installation | Outbound |
kots.io 443 |
Download the KOTS plug-in | Installation | Outbound |
*.redhat.com 443 (RHEL server only) |
Download yum-utils |
Installation | Outbound |
*.microsoft.com 443 (RHEL server only) |
Download yum-utils |
Installation | Outbound |
mirror.centos.org 443 (RHEL 8.6 server only) |
Download semanage |
Installation | Outbound |
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 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.
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:
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:
install_de_ss_airgap.sh
, which creates the Kubernetes cluster and installs Dash Enterprise as well as supporting software.config.local.sh
which contains variables used by the scripts. You’ll define some of these valuables as part of the install preparation.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 runningkubectl kots reset-password plotly-system
.
HOST_INTERNAL_REGISTRY
: The URL to the private container registry you are using for Dash Enterprise images.HOST_INTERNAL_REGISTRY_USER
: The username for the account you’ll use to push images to your private container registry.HOST_INTERNAL_REGISTRY_PASSWORD
: The password for the account you’ll use to push images to your private container registry.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 bare metal server (cannot be 443, 80, 8800, or the original 22). This will be used by the installation script to remap the Linux OpenSSH daemon (sshd
) on your bare metal server to your chosen port. Remapping this port is required because Dash Enterprise expects Dash app deployments over SSH to use port 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
.Finally, note the value for KOTS_VERSION
. You’ll need this version number in a later step.
In this step, you’ll download your Dash Enterprise license file as well as the airgap bundles required to install Dash Enterprise and the KOTS Admin Console. Note that the Dash Enterprise airgap bundle is approximately 15 GB, and
the KOTS airgap bundle is approximately 1 GB.
To download the Dash Enterprise license and airgap bundles:
KOTS_VERSION
in your config file; then select Download bundle. You’ll use this bundle to install the KOTS Admin Console in a later step.In this step, you’ll run the installation script from your bootstrap node. This script does the following:
INSTANCE_SSH_PORT
.kURL
and moves it to your bare metal server to create the Kubernetes cluster.plotly-system
namespace, in which the core system components of Dash Enterprise will be installed.~/.kube/config
) to run kubectl
commands against the Kubernetes cluster. If using a short-lived machine as your bootstrap node, we recommend transferring this file to your workstation before deleting the bootstrap node.To create the cluster and port-forward the KOTS Admin Console:
bash install_de_ss_airgap.sh
kots
install location by Enter installation path (leave blank for /usr/local/bin)
, press Enter
to accept the default./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 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:
http://<bootstrap-ip>:8800
, where <bootstrap-ip>
is the external IP address of your bootstrap node.http://localhost:8800
.ADMIN_PASSWORD
in Defining Variables in the Scripts; then select Log in. You are prompted to upload your license..airgap
file you downloaded earlier.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).When the upload is complete, the KOTS Admin Console opens to the Configure Dash Enterprise page.
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:
<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>
.
Make sure members of your organization who will be using Dash Enterprise have the right accesses. The exact steps look different depending on your environment. If your organization uses a VPN, configuring this access might involve defining and assigning VPN profiles.
Using the bare metal server IP, configure the access as follows:
Important: Port 22 is required for app developers to deploy their apps with git push
over SSH. Dash Enterprise also supports deployments over HTTPS, but not if you configure authentication using a SAML or OIDC identity provider.
If you plan to use a SAML or OIDC identity provider, make sure port 22 is open to app developers.
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>
If you provisioned a VM to use as your bootstrap node, you can now safely delete the VM. Remember to first transfer the kubeconfig file to the workstation you’ll use for cluster management with kubectl
.
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.