Chapter 6. Install the Tungsten Dashboard

There are two ways to install the Tungsten Dashboard - the standard way using a Linux server and manual configuration of Apache 2 and HAProxy, or via a Docker container.

6.1. Install the Tungsten Dashboard - Standard Method

This section describes the standard method of installing the Tungsten Dashboard when using a Linux server with Apache 2, PHP and optionally HAProxy installed locally.

Important

Please change the example values below to match your specific environment.

For example, create a new user called tungsten, group tungsten, homedir /home/tungsten:

shell> sudo useradd -m -d /home/tungsten -s /bin/bash -c "Tungsten Dashboard" -U tungsten

Note: Later on you will need to add the apache user to the tungsten group and restart apache.

Now create the Tungsten Dashboard web root directory and all needed subdirectories:

shell> sudo mkdir /volumes/data/www/tungsten
shell> sudo chown -R tungsten: /volumes/data/www/tungsten

shell> sudo su - tungsten
shell> cd /volumes/data/www/tungsten
shell> mkdir etc logs
shell> chmod 2770 logs
shell> chmod 2750 etc

Still as user tungsten, download the software using the temporary URL provided by Continuent, or login to the web download portal to obtain the software (https://www.continuent.com/downloads/), then copy to the web root directory for use in the next step:

shell> cd
shell> wget -O tungsten-dashboard-1.0.0-123.tar.gz 'TEMP_URL_PROVIDED_BY_CONTINUENT'
shell> tar xvzf tungsten-dashboard-1.0.0-123.tar.gz
shell> cd tungsten-dashboard-1.0.0-123
shell> rsync -a html/ /volumes/data/www/tungsten/html/
shell> chmod 2775 /volumes/data/www/tungsten/html

If not present, create the html/locks directory and set the permissions:

shell> mkdir /volumes/data/www/tungsten/html/locks
shell> chmod 2775 /volumes/data/www/tungsten/html/locks

6.2. Install the Tungsten Dashboard - Docker Method

This section describes the docker method of installing the Tungsten Dashboard using a pre-defined Docker container provided by Continuent containing Apache, PHP, HAProxy and the Dashboard.

6.2.1. Dashboard Docker Install - Quick Start

Below are the key steps needed to install the Tungsten Dashboard via Docker.

  • Copy the downloaded software to the target Linux host:

    desktop> scp tungsten-dashboard-docker-1.0.15-10.tar.gz tungsten@db1:
  • SSH to the target host:

    desktop> ssh tungsten@db1
  • Extract the tarball to a temporary location like your home directory on that host:

    shell> tar xvzf tungsten-dashboard-docker-1.0.15-10.tar.gz
    tungsten-dashboard-docker/
    tungsten-dashboard-docker/README
    tungsten-dashboard-docker/config.php
    tungsten-dashboard-docker/docker-compose.yml
    tungsten-dashboard-docker/dshell
    tungsten-dashboard-docker/haproxy/
    tungsten-dashboard-docker/haproxy/haproxy.cfg
    tungsten-dashboard-docker/hastat
    tungsten-dashboard-docker/settings.d/
    tungsten-dashboard-docker/settings.d/apiAuth.json
    tungsten-dashboard-docker/settings.d/apiPassword.json
    tungsten-dashboard-docker/settings.d/apiSSL.json
    tungsten-dashboard-docker/settings.d/apiUser.json
    tungsten-dashboard-docker/settings.d/apiVersion.json
    tungsten-dashboard-docker/settings.d/startExpanded.json
    tungsten-dashboard-docker/settings.d/useHAProxy.json
    tungsten-dashboard-docker/tungsten_generate_haproxy.pl
    tungsten-dashboard-docker/tungsten-dashboard-docker-saved-1.0.15-10.tar
  • Proceed to the extracted directory:

    shell> cd tungsten-dashboard-docker
  • Inform the Docker server of the new Dashboard image to install:

    shell> sudo docker load  --input tungsten-dashboard-docker-saved-1.0.15-10.tar
  • Create Dashboard login credentials, i.e. user tungsten with password secret:

    shell> (cd etc; htpasswd -c .htpasswd tungsten)
  • Add explicit etc/hosts entries under the extra_hosts sections for both services, haproxy and dashboard:

    shell> vi docker-compose.yml
  • Create cluster-specific HAProxy entries one of two ways:

    The following will only work when a valid /etc/tungsten/tungsten.ini file exists:
    shell> ./tungsten_generate_haproxy.pl --port 8201 >> haproxy/haproxy.cfg

    ~OR~

    The following will only work when a valid Tungsten install and /etc/tungsten/tungsten.ini file exists:
    shell > tpm generate-haproxy-for-api --port 8201 >> haproxy/haproxy.cfg
  • Launch the containers:

    shell> sudo docker-compose up -d
  • Validate that everything is running properly:

    shell> sudo docker ps
    shell> sudo docker logs haproxy
    shell> sudo docker logs dashboard
  • View the GUI in a browser:

    Browse to http://localhost:8080
    Click on "Please click here to auto-define an existing service (recommended)"
    Add the new cluster using:
      Host Name: haproxy
      Port Number: 8201

6.2.2. Dashboard Docker Install - Details

  • Create the .htpasswd file under the etc/ folder with your desired login and password for the Dashboard:

    shell> (cd etc; htpasswd -c .htpasswd tungsten)
  • Edit the config.php file and add the login you just created to the administrators line. The tungsten user is pre-populated.

  • Create the HAProxy frontend and backend entries from your existing INI by running either tpm generate-haproxy-for-api or the enclosed ./tungsten_generate_haproxy.pl - for example, to append the results to the haproxy/haproxy.cfg file:

    shell> ./tungsten_generate_haproxy.pl >> haproxy/haproxy.cfg
  • Populate /etc/hosts inside the container(s) by adding indented lines under the extra_hosts: directive:

    shell> vi docker-compose.yml
    ...
    services:
      dashboard:
        extra_hosts:
          db1: 10.0.0.101
          db2: 10.0.0.102
          db3: 10.0.0.103
          db4: 10.0.0.104
          db5: 10.0.0.105
          db6: 10.0.0.106
    ...
      haproxy:
        extra_hosts:
          db1: 10.0.0.101
          db2: 10.0.0.102
          db3: 10.0.0.103
          db4: 10.0.0.104
          db5: 10.0.0.105
          db6: 10.0.0.106
    ...
  • Run the two containers via the sudo docker-compose up -d command.

  • Validate the containers via the sudo docker ps command.

  • Point your browser to http://localhost:8080

  • Click on "Please click here to auto-define an existing service (recommended)"

  • Add the new cluster using hostname haproxy and the frontend port number(s) created above, i.e. 8201

NOTES

  • The Dashboard sees HAProxy under the hostname haproxy on port 8090-809X (depending on the haproxy config).

  • The dashboard and haproxy containers are on an internal network that can see each other with these hostnames.

  • The netcat command nc is required to use the included hastat script:

    shell> yum -y install nc
  • Use the enclosed dshell script to ssh to the container by providing the CONTAINER ID listed with docker ps as the only argument:

    shell> sudo docker ps
    shell> ./dshell {container name or containerid}

    For example:

    shell> ./dshell dashboard
    shell> ./dshell haproxy

6.2.3. Docker Compose Quick Reference Guide

Docker-compose Install Summary

Note

NOTE: To install a different version of Compose, substitute 1.29.2 below with the version of Compose you want to use...

shell> sudo curl -L "https://github.com/docker/compose/releases/download/1.29.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
shell> sudo chmod +x /usr/local/bin/docker-compose
shell> sudo ln -s /usr/local/bin/docker-compose /usr/bin/docker-compose
shell> docker-compose --version
   

      Click here to see the Docker documentation for more information about docker-compose.    

Docker-compose Key Tasks Summary

== Start in foreground mode:
shell> sudo docker-compose up

== Start as a daemon:
shell> sudo docker-compose up -d

== Stop all containers:
shell> sudo docker-compose down

6.2.4. Docker Quick Reference Guide

== View the logs from a container:
shell> sudo docker logs {ID|name}

== Login to the shell on a container:
shell> sudo docker exec -it {ID|name} /bin/bash
~or~
shell> ./dshell {ID|name}

== List all containers:
shell> sudo docker ps

== Restart a container:
shell> sudo docker restart {ID}

6.2.5. Dashboard Docker Install - Troubleshooting

  • To install tools for checking connectivity on a container:

    shell> ./dshell {container name or containerid}
    shell> apt update
    shell> apt install iputils-ping telnet netcat-openbsd curl jq
  • To check the HAProxy status:

    shell> ./dshell haproxy
    root@f57d517b7acf:/# echo "show stat" | nc -U /var/lib/haproxy-stats-socket
  • To check the Manager reachability:

    shell> ./dshell haproxy
    root@f57d517b7acf:/# /usr/bin/curl -s  --insecure --user tungsten:secret  --request GET 'https://db1-demo.continuent.com:8090/api/v2/manager/cluster/status/' | jq .
  • ERROR:

    Cannot raise FD limit to 8066, limit is 1024

    CAUSE:

    /etc/sysconfig/docker has incorrect options configured

    SOLUTION:

    shell> sudo docker-compose down
    shell> vi /etc/sysconfig/docker
    
    ==> CHANGE FROM:
    OPTIONS="--default-ulimit nofile=1024:4096"
    ==> TO:
    #OPTIONS="--default-ulimit nofile=1024:4096"
    OPTIONS=""
    
    shell> sudo service docker restart
    shell> sudo docker-compose up -d

    ERROR DETAILS:

    shell> sudo docker-compose up
    
    ...
    haproxy      | [NOTICE] 161/185553 (1) : haproxy version is 2.3.10-4764f0e
    haproxy      | [NOTICE] 161/185553 (1) : path to executable is /usr/local/sbin/haproxy
    haproxy      | [ALERT] 161/185553 (1) : [haproxy.main()] Cannot raise FD limit to 8066, limit is 1024.
    haproxy exited with code 1
    ...
    
    shell> ps -ef | grep docker
    root      2681     1  0 12:57 ?        00:00:10 /usr/bin/dockerd --default-ulimit nofile=1024:4096
  • ERROR:

    Dashboard shows "Internal Server Error" in a browser; logs show "Could not open password file: /var/www/html/etc/.htpasswd"

    CAUSE:

    Forgot to create the .htpasswd file

    SOLUTION:

    shell> cd tungsten-dashboard-docker
    shell> sudo htpasswd -c etc/.htpasswd tungsten

    ERROR DETAILS:

    shell> sudo docker logs dashboard
    
    [Tue Jun 15 19:37:23.074342 2021] [authn_file:error] [pid 20] (2)No such file or directory: [client 222.33.44.55:63370] AH01620: Could not open password file: /var/www/html/etc/.htpasswd
  • COMMAND:

    sudo docker-compose up

    ERROR:

    docker.errors.DockerException: Error while fetching server API version: ('Connection aborted.', FileNotFoundError(2, 'No such file or directory'))

    CAUSE:

    Docker server process not running

    SOLUTION:

    Start the Docker server process

6.3. Dashboard Initial JSON Configuration

Place under settings.d/ as needed:

apiAuth.json
{
    "apiAuth": 1
}

apiPassword.json
{
    "apiPassword": "default"
}

apiSSL.json
{
    "apiSSL": 1
}

apiUser.json
{
    "apiUser": "default"
}

apiVersion.json
{
    "apiVersion": 2
}

useHAProxy.json
{
    "useHAProxy": 1
}