The following prerequisites are common across both deployment methods (docker-compose and helm):

In order to install Tungsten Dashboard using the Docker Compose method you will require a host configured with the following minimum requirements:

shell> docker --version

shell> docker-compose --version

In order to install Tungsten Dashboard in Kubernetes you will require a staging host to initiate the installation, with a minimum of the following requirements:

Additionally your cluster must have an access to the docker image file provided in the installation package. Our recommendation is for you to host a private registry of your own in order to manage the images in a centralized manner. This is accepted as the best practice for Kubernetes.

Alternatively you can upload the images as local images directly to the cluster you are using and rely on the local registry of the cluster, please bear in mind how you achieve this depends on the details of your cluster. In addition you should alter the image pull policies in the provided yaml files to match the cluster configuration.

For example to upload an image to a kind cluster you could use the following:

shell> kind load image-archive target/images/tungsten-dashboard_{{.VERSION}}-linux_{{.CURRENT_ARCH}}.tar

shell> kubectl version --client

shell> helm version

shell> aws eks --region <region-code> update-kubeconfig --name <cluster-name>

Download the Tungsten Dashboard TAR package from the Continuent Download Portal and place the file into the /opt/continuent/software directory on the staging host. From there, unpack the file:

shell> cd /opt/continuent/software
shell> tar zxvf tungsten-dashboard-8.0.0-10.tar.gz
shell> cd /opt/continuent/software/tungsten-dashboard-8.0.0-10

Kubernetes installation via helm uses a declarative approach to configuring the Dashboard. To get started, you need to adjust the values.yaml or your custom yaml file to define settings before you run the installation script.

Declare the clusters:

Find the following line in the values.yaml file:

clusters: []

Replace the line with a configuration that matches your clusters. For example:

clusters: 
  - host: "db1.example.com"
    namespace: "dev"
    api-user: "sample-user"
    api-password: "<clear-text-password>"
    tcp-port: 11999
    api-port: 8090
    api-ssl: true
    ssl: true
    cert: "<base64-encoded-certificate>"
    api-cert: "<base64-encoded-certificate>"
    hostname-validation: true

You can add as many clusters as you'd like using the "- <cluster>" syntax.

Declare the Application Configuration:

Next, adjust the application configuration as necessary. See Section A.3, “The values.yaml file” for more details on each setting. Note that the configs here are in camelCase while in the final JSON they're snake_case

config: 
  env: "production"
  version: "8.0.0"
  configPath: "/app/persistent/"
  logType: "console-edn"
  helm: true
  domain: ""  
  path: "" 
  port: 4090 
  ssl: false
  sslPort: 4091
  browserPort: 4090
  clustersConnectOnStart: false
  topologyStartupDiscover: false
  topologyCleanOnExit: false
  defaultRestPort: 8090 
  defaultTcpPort: 11999
  hostnameValidation: true
  restTimeout: 15000

In the configuration take note of the following 5 values: domain, port, browserPort, path and restTimeout.

User Credentials:

Adjust the default user credentials or be prompted for a default user during installation. The install.pl script itself creates only one user, if you want multiple users define them here.

users: 
  - role: admin # currently only admin role is supported.
    username: jane-doe
    password: <clear-text-password>

Passwords in yaml file are provided as clear text, during installation they're encrypted and final users.json will have hashed passwords on the server.

Configure Ingress (if required):

To enable Dashboard-specific ingress locate the following entries and adjust accordingly:

ingress:
  enabled: false # When true, creates dashboard ingress resource

  # You must create the IngressClass and then add it here.
  # Example of a controller: nginx see https://github.com/kubernetes/ingress-nginx for more information
  className: "" # ingressClassName ie. nginx

  # use config field's domain, path and port for ingress.
  # to fully control your setup set this to false and specify extraHosts.
  hostFromConfig: true

  # TLS config for ingress.
  # To use this create a secret with any name and add it here.
  # The secret must contain both base64 encoded certificate and the key as base64 encoded values.
  # See https://kubernetes.io/docs/concepts/services-networking/ingress/#tls for more
  tls: []
  #  - secretName: chart-example-tls
  #    hosts:
  #      - chart-example.local

Being Installation

To begin the installation for kubernetes execute the following:

shell> cd /opt/continuent/software/tungsten-dashboard-8.0.0-10
shell> ./install.pl -m kubernetes

The following example shows the output from running the installation and the prompts that will require answering:

shell> ./install.pl -m kubernetes

Please enter custom values YAML file [values.yaml]:

Please enter preferred admin user name: admin-user

Please enter a password for admin user: admin-password

Please enter the domain for your application without schema or port.
Domain for your application [127.0.0.1]: example.com

Please enter the dashboard server port [4090]:

The path is the part of the URL that comes after the domain.
For example, if your application is hosted at http://example.com/dashboard, the path is dashboard.
Please enter the path for your application [empty]:

WARNING: Ingress is currently not enabled!
Dashboard will not be accessible without port-forwarding from outside the cluster.
Do you want to proceed with the current configuration? [y/N]: y

WARNING: TLS is not configured in your ingress settings!
Running the dashboard without TLS encryption is not recommended for production use.
To enable TLS, modify values.yaml to include your TLS secret and domain configuration:

ingress:
  tls:
  - secretName: your-tls-secret
    hosts:
      - your.domain.com

Do you want to proceed with insecure configuration? [y/N]: y

With current settings your base url will be: http://example.com:4090
This is the url the browser will load the resources for the dashboard from.

Please input the container registry URL where Tungsten Dashboard image is stored (without a tag) [tungsten-dashboard]:

Please enter Tungsten Dashboard version tag [8.0.0]:

Current Kubernetes context is set to: arn:aws:eks:us-east-1:00000000000:example-cluster
Do you want to proceed with the currently selected Kubernetes context? [y/N]: y

Installing Tungsten Dashboard Helm chart...
NAME: tungsten-dashboard
LAST DEPLOYED: Mon Apr 14 16:43:52 2025
NAMESPACE: tungsten-dashboard
STATUS: deployed
REVISION: 1
Waiting for deployment to become ready...
deployment.apps/tungsten-dashboard condition met

Installation completed!

To uninstall current deployment, simply run 'helm uninstall tungsten-dashboard --namespace tungsten-dashboard'

shell> helm uninstall tungsten-ui --namespace tungsten-ui

shell> kubectl -n tungsten-dashboard delete secret tungsten-dashboard-secret;
# check if tungsten-dashboard-vol exists.
shell> kubectl -n tungsten-dashboard get pvc;
# if it does, remove it with:
shell> kubectl -n tungsten-dashboard delete pvc tungsten-dashboard-vol;

Once logged in, you are presented with the following view:

Figure 4.1. Dashboard Front Page Overview

An explanation of each highlighted area is as follows:

Navigation

On the left you can see the primary navigation. Hover over it to expand it, and use the button at the bottom of the side bar to lock it in place.

Cluster Filters

At the top you have the cluster filters. Clicking any of them will take you to the Clusters page and show you the clusters that are reporting the filtered status.

Search & Notifications

On the far right of the top bar you have:

To start using the Dashboard the first recommended action is to create your own user account. Login with the installation default account, then open the sidebar by hovering over it and click "User Management". On this page click the "Add" button and fill in the details of the new account. Next, click the logout button and log back in using the account you just created.

In Summary:

Figure 4.2. Add User Form

User accounts are stored in a file on the Dashboard server. This file is intended to be stored in the persistent volume of the Dashboard. In that file you'll find the email, username and hash of the password. Future logins work by matching the incoming hash against the stored one.

Each login returns a JWT token that the browser uses to communicate with the backend. This signed token contains basic JWT details and the username. While the content of the token can be decoded with base64, altering the token in any way will cause the backend to reject it. When a token is rejected, the backend closes the websocket session from the browser.

Once you've logged in, click the "Add cluster" button on the fron tpage (see Figure 4.3, “Cluster Front Page - Add Cluster”) or the clusters page. This opens up a form which asks for the following details:

Figure 4.3. Cluster Front Page - Add Cluster

Figure 4.4. Add Cluster Form

When cluster connection details are added to the Dashboard, the changes are written to both the clusters.json file and into the Dashboard's active memory. The Dashboard's Topology sub-system is aware when these changes occur, and will gather the new details from the cluster via the RestAPI, then store the response into the /app/persistent/dynamic/clusters.edn file, which keeps a map of the hosts by cluster.

When the Dashboard connects to a cluster, one host is selected for each service in the clusters.edn file, and that host is then called via the Rest API to get the initial data for the cluster. This is followed by a TCP connection to the cluster which updates the data in real time.

Each cluster connection is hosted in a virtual thread inside the JVM. If an error occurs, the Dashboard attempts to select a new host and restart the cluster connection unless the error is significant enough (i.e. "invalid certification" or credential data), at which point the Dashboard stops further connection attempts.

Once you've added the desired clusters, you can use the Dashboard or Clusters pages to monitor the status of these clusters in real-time. While the Dashboard page provides limited data, the Clusters page allows you to view detailed information and execute corrective actions to a cluster as needed.

From this page you can find a quick status overview of any of the clusters you've connected the dashboard to. Clusters are split into small "widgets" on the page. (See Figure 5.1, “Front Page Interface”)

Each widget shows:

Figure 5.1. Front Page Interface

On the clusters page you can review your cluster data. Excecute actions to a cluster, and add or remove clusters from the Dashboard. (See Figure 5.2, “Populated Cluster Front Page”)

Figure 5.2. Populated Cluster Front Page

The first tools available to you on the clusters page are the collapse/expand and simple/advanced view toggles available just below the top navigation. (See Figure 5.3, “Cluster Tool Bar”)

Collapse/expand opens or closes all clusters visible on the page. While simple / advanced view toggle switches what columns are shown to you.

Figure 5.3. Cluster Tool Bar

Below the toolbar you can find the clusters themselves:

Figure 5.4. Cluster Header Detail

A description of each item is as follows:

Figure 5.5. Parent Service Actions/Operations

Following service actions you have Dashboard specific actions for each service:

Figure 5.6. Edit Cluster Form

The cluster's host details are displayed as a table. (See Figure 5.7, “Cluster Host Table (CAA)”) It has fields such as:

Figure 5.7. Cluster Host Table (CAA)

In the host row actions dropdown (See Figure 5.8, “Primary Host Operations” & Figure 5.9, “Replica Host Operations”) you can find a set of operations the dashboard can post to the cluster's RestAPI for each of the hosts. Note that the host's Role affects what actions are visible. To see more details about operations see Chapter 8, Operations

Figure 5.8. Primary Host Operations

Figure 5.9. Replica Host Operations

This page lists the current users stored in the Dashboard with their role, username and email. (See Figure 5.10, “User Management Page”)

From here you can add or remove users as you desire. (See Figure 5.11, “Add User Form”)

Figure 5.10. User Management Page

Figure 5.11. Add User Form

The install.pl script is a command-line tool for installing the Tungsten Dashboard. This document provides a detailed guide on how to use this script.

Usage

Where:

For example, to install using Docker Compose, you would run:

shell> ./install.pl -m docker-compose

To install using Kubernetes, you would run:

shell> ./install.pl -m kubernetes

If no method is specified, the script will prompt you to choose a method interactively.

Prerequisites check

The script checks for prerequisites based on the selected installation method:

If the required tools are not found, the script will display an error message and exit. For more information on prerequisites, see Chapter 2, Prerequisites

Interactive Prompts

During execution, the script will prompt you for various pieces of information, such as the admin username and password, the domain for your application, and the path for your application. Please follow the prompts and provide the necessary information.

getcert.pl is a script designed to fetch certificates from a specified remote host. Once fetched, these certificates can be copied and pasted into the dashboard form, or included in the values.yaml during installation.

Usage

Where:

Examples

Fetch the API certificate from a host:

shell> ./getcert.pl --api db1.continuent.com

Fetching API certificate from db1.continuent.com:8090 ...

-----BEGIN CERTIFICATE-----
MIIDBDCCAeygAwIBAgIBAzANBgkqhkiG9w0BAQsFADA8MTowOAYDVQQDDDFNeVNR
... rest of certificate content ...
LwZn40KuWnk=
-----END CERTIFICATE-----

Please copy this API certificate (including BEGIN and END markers) into the UI form

Fetch the TCP certificate from a host on a specific port:

shell> ./getcert.pl --tcp --port 11999 {HOSTNAME}

Redirecting Output to a File

The output of the script can be redirected to a file using the > operator. For example:

shell> ./getcert.pl --api {HOSTNAME} > cert.txt

This will save the certificate content into cert.txt without any additional verbose output.

When deploying through kubernetes there are two options available, these are as follows:

...
 api-ssl: true
 api-cert: "<base64-encoded-certificate>"
 ssl: false
...

...
 api-ssl: true
 api-cert: "<base64-encoded-certificate>"
 ssl: true
 cert: "<base64-encoded-certificate>"
 hostname-validation: false
...

These can be used on standalone or composite services of the clusters. They include cctrl operations like heartbeat, recover, switch and failover as well as the service's policy switching.

To switch a policy for a service click on the currently set policy in the service header and click on the policy you want the service to be set into. In the composite cluster, you can set different policy for each service in a composite cluster.

To execute service operations themselves do the following:

Figure 8.1. Service Policy Dropdown

Figure 8.2. Cluster Lock Dropdown

Figure 8.3. Composite Service Operations

Figure 8.4. Service Operartions

To execute a host operation please follow the following steps:

Figure 8.5. Primary Host Operations

Figure 8.6. Replica Host Operations

Once clicked the operation will lock the service and block it (See Figure 8.7, “Blocked Cluster”) from all dashboard users for the duration of the operation. By default the Dashboard has a 120 second timeout for operations. Please bear in mind that some operations may take much longer, especially large clusters. For these use cases it is recommended to adjust the rest_timeout property in the config.json file.

Figure 8.7. Blocked Cluster

In addition to the control operations listed in the previous sections there are several operations unique to the Dashboard and it's interaction with Tungsten Clusters.

Additionally for dataservices you can use "Lock" & "Unlock" operations from the lock dropdown next to the service actions. (See Figure 8.3, “Composite Service Operations”) These prevent other dashboard users from executing operations on the service without first unlocking the cluster by hand.

Figure 8.8. Cluster Edit Form

Question: I lost my password and got locked out of the Dashboard

Answer:

To recover access another user can recreate your account for the dashboard. Or if you lost all access to the dashboard from all accounts. Do the following steps: (for docker-compose installations)

When the user file does not exist the Dashboard will recreate the default user for you when it restarts, use this to recover access

Problem : You receive a 404 after "test-connection" was successful

This situation happens when the dashboard cannot resolve the domain names from api/v8/manager/cluster/topology response to ips it can connect to. This breaks the load balancing of the Dashboard. To resolve the issue use any RestAPI tool to fetch the response from this end point.

For example:

{
    "payloadType": "ClusterTopologyPayload",
    "payloadVersion": "1",
    "payload": {
        "topology": "CLUSTERED_PRIMARY",
        "name": "oulu",
        "datasources": [
            {
                "name": "db21",
                /* the value of "host" must be resolvable by Dashboard's dns */
                "host": "db21", 
                "role": "master"
            },
            {
                "name": "db22",
                /* the value of "host" must be resolvable by Dashboard's dns */
                "host": "db22",
                "role": "slave"
            },
            {
                "name": "db23",
                /* the value of "host" must be resolvable by Dashboard's dns */
                "host": "db23",
                "role": "witness"
            }
        ],
        "routers": [...]
    }
}

Collect the host values from the response and SSH to the Dashboard container. To test the dns you've got from the response. Before we can do so we need to install some tools. Run the commands:

shell> apt upgrade;
shell> apt install dnsutils;

Followed by:

shell> dig -v;
# ie. DiG 9.18.30-0ubuntu0.24.04.2-Ubuntu

Next test the hosts you got from the topology response, for example:

shell> dig db21;
"
; <<>> DiG 9.18.30-0ubuntu0.24.04.2-Ubuntu <<>> db21
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 30152
;; flags: qr rd ra; QUERY: 1, ANSWER: 1, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: ab4ead051ab4fa5d (echoed)
;; QUESTION SECTION:
;db21.        IN  A

;; ANSWER SECTION:
db21.     5 IN  A XX.XXX.XX.XXX" # <---- note valid ip in the answer.
"

;; Query time: 4 msec
;; SERVER: XX.XX.X.XXX#53(XX.XX.X.XX) (UDP)
;; WHEN: Wed Apr 09 12:13:03 UTC 2025
;; MSG SIZE  rcvd: 65
"

Example of a failed dns resolution:

shell> dig db20;
"
; <<>> DiG 9.18.30-0ubuntu0.24.04.2-Ubuntu <<>> db20
;; global options: +cmd
;; Got answer:
;; ->>HEADER<<- opcode: QUERY, status: NXDOMAIN, id: 12636
;; flags: qr rd ra; QUERY: 1, ANSWER: 0, AUTHORITY: 0, ADDITIONAL: 1

;; OPT PSEUDOSECTION:
; EDNS: version: 0, flags:; udp: 1232
; COOKIE: ad741d4ba38cc0a7 (echoed)
;; QUESTION SECTION:
;db20.        IN  A"

Note how the dig never got a valid ip back like in the previous example.

Make sure that the hosts returned by the topology end point can be resolved to proceed further. Once they can re-add the cluster to the dashboard or reload it topology by the reload action or by making a small change to it, such as changing the first host.