TethysDash System installation via Docker

Note

We are in the process of refining these instructions as we perform additional testing on new machines. Please let us know of any questions or suggestions.

The installation of the integrated TethysDash System is greatly facilitated with the use of Docker container technology. With a Docker Engine installed on your target environment, you can focus on the configuration (and use) of the TethysDash System, and let the container engine set up, run and orchestrate the various underlying components.

Before proceeding, please have in place the general requirements and any optional settings described in previous sections.

Note

You do not need to have a separate installation of the PostgreSQL server on your target machine. As indicated below, there's also a Docker image with PostgreSQL (server and particular database) ready to be used by TethysDash.

1. Create a new directory on your target server and navigate to it

$ mkdir /path/to/tethysdash
$ cd    /path/to/tethysdash

2. Download the following base files under your designated directory above:

$ wget http://docs.mbari.org/tethysdash/install/docker/setenv.sh
$ wget http://docs.mbari.org/tethysdash/install/docker/TethysDash.conf
$ wget http://docs.mbari.org/tethysdash/install/docker/docker-compose.yml

The files are:

File Purpose
setenv.sh Define required environment variables
TethysDash.conf Define TethysDash configuration
docker-compose.yml Specify the TethysDash and PostgreSQL Docker containers

3. Edit the files as needed for your TethysDash System instance

3.1 Environment variables

As indicated in setenv.sh, the following environment variables must be defined prior to running the containers:

Variable Purpose
POSTGRES_PASSWORD Desired password for the Postgres super user
PG_TD_PASSWORD Desired password for the 'tethysdash' user in Postgres
POSTGRES_DATA Postgres data directory
POSTGRES_HOST_PORT Host port where the Postgres service will be exposed. Useful to be able to connect to the 'tethysdash' database from outside the container.
TETHYSDASH_CONF Path to TethysDash.conf
TETHYSDASH_DATA Directory for the data directly managed by TethysDash
TETHYSDASH_EMAILLOGS Directory under which all email logs will be stored
TETHYSDASH_HOST_PORT Host port where the TethysDash service will be exposed
LRAUV_REPOS Directory containing the LRAUV configuration and mission git clones. See below.

LRAUV_REPOS

The clones (subdirectories) under the ${LRAUV_REPOS} directory must be named lrauv-config and lrauv-mission, respectively. Also, if the referenced remote repositories are private, this directory should contain the following files:

  • id_rsa: the SSH private key to access the repositories;
  • known_hosts: as handled by ssh.

Path-related settings in setenv.sh use the current directory, $PWD, as a base directory. This is mainly for illustration purposes. Edit the values as needed depending on your particular storage requirements/policies.

Note

You can define these environment variables in whatever way appropriate according to your own practices/policies. The setenv.sh file (which will be sourced prior to running the containers as explained below), is mainly provided for illustration.

3.2 TethysDash configuration

Along with the key parameters already explained and captured via environment variables, TethysDash.conf serves as the master configuration for the TethysDash component. Besides the optional settings described in a previous section, the most relevant properties that you will need to provide or adjust are as follows (please see contents of TethysDash.conf for additional details):

  • external - This section defines various URLs, in particular the external URLs corresponding to the main TethysDash components. For these, you will typically be adjusting the server part depending on how you will be exposing the system externally.

    • tethysdash - External URL of the TethysDash web application;
    • fleetstatus - External URL of the FleetStatus interface;
    • useradmin - External URL of the User/Admin interface.

    This section also includes:

    • watchbill - This URL is optional. If given, a link will be included to the right of the TethysDash and FleetStatus links in the User/Admin UI.
  • auth - User authentication. In this section, provide a strong password (used to generate/verify user authentication tokens); and a length of time for user token expiration (user will have to login again after this period of inactivity).

  • admin - Administrative settings. This section is mainly to indicate the users that will initially have admin privilege on the system. Please indicate at least one email address in admin.admins.

  • defaultVehicle - Which vehicle to show when no vehicle has been selected yet. The name should correspond to an existing vehicle in the indicated LRAUV configuration repository.

  • mail - Email settings. The key settings that must be provided in this section are:

    • mail.host - Default server to use for both email send and receive
    • mail.imap.host - IMAP server in case is different from default server
    • mail.imap.user/mail.imap.password - Username/password to access corresponding tp IMAP server
    • mail.smtp.host - SMTP server in case is different from default server
    • mail.smtp.user/mail.smtp.password - Username/password to access corresponding tp SMTP server

3.3 Docker Compose

docker-compose.yml references the Docker containers needed for the TethysDash System. This file will be processed by the Docker Compose tool. Please install Docker Compose to proceed.

Note

Except for the specification of the particular images (including the tag), docker-compose.yml does not need to be edited. Instead, the relevant settings are to be indicated via environment variables as explained in the previous section.

Although you won't in general need to edit docker-compose.yml, here is a brief explanation of what is being specified there.

Containers. There are two containers (services) defined: the TethysDash application itself, and the PostgreSQL server/database to be used by TethysDash.

Volumes. The volumes sections establish a mapping between host directories/files and corresponding directories/files in the containers.

Ports. The ports sections establish a mapping between host ports and corresponding ports in the containers.

Environment. The environment sections allow to define environment variables for the corresponding containers.

Images. The Docker images for the tethysdash and tdpostgres containers are served from Docker Hub at mbari/tethysdash and mbari/tdpostgres, respectively.

Note

You will need to create an account at Docker Hub, and then contact us regarding access to these images.

4. Launch the system

Once the information in the base files has been captured as needed (including the required vehicle configuration and mission file Git clones), we are ready to launch the TethysDash System as follows.

4.1 Set the required environment variables

$ source setenv.sh    # or use whatever other mechanism to define the required variables

4.2 Login to Docker Hub

$ docker login

4.3 Launch the Postgres and TethysDash containers

$ docker-compose up -d

Creating network "tethysdash_default" with the default driver
Pulling tdpostgres (mbari/tdpostgres:9.3.14)...
9.3.14: Pulling from mbari/tdpostgres
357ea8c3d80b: Pull complete
...
Digest: sha256:...
...
Pulling tethysdash (mbari/tethysdash:2.4.0)...
2.4.0: Pulling from mbari/tethysdash
...
25bd065f3d45: Pull complete
Digest: sha256:...
Creating tdpostgres
Creating tethysdash

The containers should now be running:

$ docker ps
CONTAINER ID        IMAGE                     COMMAND                  CREATED             STATUS              PORTS                    NAMES
450f68b3eff7        mbari/tethysdash:2.4.0    "catalina.sh run"        2 hours ago         Up 2 hours          0.0.0.0:80->8080/tcp     tethysdash
16963fd8b624        mbari/tdpostgres:9.3.14   "/docker-entrypoin..."   2 hours ago         Up 2 hours          0.0.0.0:5432->5432/tcp   tdpostgres

To inspect the logs:

$ docker logs -f --tail=100 tethysdash
...
^C

Assuming the default host port 80 indicated via TETHYSDASH_HOST_PORT (in setenv.sh), you should now be able to open the following URLs in your browser:

  • http://localhost/TethysDash/
  • http://localhost/FleetStatus/
  • http://localhost/

In particular, go to http://localhost/ and click "Create account" to create at least one of the accounts indicated with the admin.admins property in TethysDash.conf. Then login with the corresponding email address. As an admin you will then have available all the functions provided by TethysDash, FleetStatus, and the User management interfaces.

Running an LRAUV vehicle simulator

To greatly facilitate testing of the overall system, an LRAUV vehicle simulator container has been made available. Please follow these instructions.

To shutdown the system:

$ docker-compose down
Stopping tethysdash ... done
Stopping tdpostgres ... done
Removing tethysdash ... done
Removing tdpostgres ... done

To stop and restart individual containers:

$ docker stop tethysdash
$ docker start tethysdash
$ docker restart tethysdash

Enabling a new version of a Docker image

Specific instructions will be reported in each case, but the typical sequence —with the TethysDash container as an example— is:

  • Edit docker-compose.yml to adjust the value of services.tethysdash.image to indicate the new image location or tag, for example:

    services:
      tethysdash:
        ...
        image: mbari/tethysdash:2.4.0
        ...
    
  • Explicitly pull the new image (to reduce down time while restarting TethysDash with the next commands):

    $ docker pull mbari/tethysdash:2.4.0
    
  • Stop current TethysDash container:

    $ docker stop tethysdash
    
  • Start the new TethysDash container:

    $ docker-compose up -d
    

Note

The above Docker set-up should in general be complemented with appropriate mechanisms toward a production environment. Additional aspects to consider include: logging, data backups, making your TethysDash instance externally visible, etc. Please check with your sysadmin.