TethysDash System installation via Docker¶

Note

We are in the process of refining these instructions as we perform additional testing and deployments 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

TethysDash uses a PostgreSQL database. However, 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 ready to be used by TethysDash.

1. Create a new directory¶

Create a new directory on your target machine for TethysDash purposes:

mkdir -p /path/to/tethysdash

2. Get the installation template¶

Go to the releases page to get the latest template for the docker based installation. The template is a small set of text files to facilitate the configuration and execution of the system. You will download a tarball tethysdash-instance-template.tgz containing such files.

Please see the releases page for more details for the particular releases. In general, the procedure is as follows.

Expand the tarball on your target machine:

cd /path/to/tethysdash
tar xf path/to/tethysdash-instance-template.tgz

The expanded directory tree should look like this:

    .
    ├── README.md
    ├── setenv.sh
    ├── config
    │   ├── TethysDash.conf
    │   ├── miscLinks.json
    │   ├── stations.json
    │   └── <other files>
    └── docker-compose.yml

The files are:

File	Purpose
`README.md`	A brief version of these instructions
`setenv.sh`	Required environment variables
`config/TethysDash.conf`	TethysDash configuration
`config/miscLinks.json`	Optional list of links to include in Dash's dropdown menu
`config/stations.json`	Optional list of stations for the map
`docker-compose.yml`	Docker specification of TethysDash services

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

3.1 Environment variables¶

As indicated in setenv.sh, unless otherwise noted, 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`	Directory containing TethysDash.conf.
`TETHYSDASH_DATA`	Directory for the data directly managed by TethysDash.
`TETHYSDASH_LOGS`	(OPTIONAL) Directory to map the TethysDash log location.
`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.

LRAUV_REPOS

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

lrauv_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 settings captured via environment variables as explained above, conf/TethysDash.conf serves as the primary configuration for your TethysDash instance.

The most relevant properties that you will need to provide or adjust, are as follows (please see contents of conf/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;
- dashui - External URL of the Dash UI;
- useradmin - External URL of the User/Admin interface.
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 (the 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.
mail - Email settings. The key settings that must be provided in this section are:
- host - Default server to use for both email send and receive;
- imap.host - IMAP server in case is different from default server;
- imap.user/imap.password - Username/password to access corresponding tp IMAP server;
- smtp.host - SMTP server in case is different from default server;
- smtp.user/smtp.password - Username/password to access corresponding tp SMTP server;

3.3 Docker Compose¶

docker-compose.yml specifies the Docker containers that comprise the TethysDash System. This file will be processed by the Docker compose command.

Note

Except for the specification of the particular version of the images, docker-compose.yml does not in general 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 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

$ docker login

4.3 Launch the containers¶

$ docker compose up -d

Creating network "tethysdash_default" with the default driver
Pulling tdpostgres (mbari/tdpostgres:9.4.19)...
...
Pulling tethysdash (mbari/tethysdash:4.5.2)...
...
Creating tdpostgres ... done
Creating tethysdash ... done

The containers should now be running:

$ docker ps
CONTAINER ID   IMAGE                     COMMAND                  CREATED          STATUS          PORTS                                         NAMES
f5fb0ff8f907   mbari/tethysdash:4.5.2    "./delayedCatalina.sh"   20 seconds ago   Up 15 seconds   0.0.0.0:18080->8080/tcp, :::18080->8080/tcp   tethysdash
8fe8b566fe9c   mbari/tdpostgres:9.4.19   "docker-entrypoint.s."   23 seconds ago   Up 20 seconds   0.0.0.0:15432->5432/tcp, :::15432->5432/tcp   tdpostgres

4.4 Inspect the logs¶

To inspect the application launch itself:

$ docker logs -f --tail=100 tethysdash

To inspect the main TethysDash application log:

$ docker exec -it tethysdash tail -f /usr/local/tomcat/logs/main.log

Or, if you are using the TETHYSDASH_LOGS volume mapping indicated above:

$ tail -f td_logs/main.log

5. Use the system¶

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

In particular, go to http://localhost:18080/dash4/, click "Sign in" and then 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 have available all the functions provided by the TethysDash system.

Running an LRAUV vehicle simulation

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

To shut down the system:

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

To stop and restart individual containers:

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

Enabling a new version of a Docker image

Please see the releases page, and get in touch if you have any questions.

Please note:

The above set-up should in general be complemented with appropriate mechanisms toward a production environment. Additional aspects to consider include:

Making your TethysDash instance externally visible
Do not use this as a standalone server; it should be used behind a proxy
Data backups
Logging

Please check with your sysadmin.

TethysDash System installation via Docker¶

1. Create a new directory¶

2. Get the installation template¶

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

3.1 Environment variables¶

3.2 TethysDash configuration¶

3.3 Docker Compose¶

4. Launch the system¶

4.1 Set the required environment variables¶

4.2 Login to Docker Hub¶

4.3 Launch the containers¶

4.4 Inspect the logs¶

5. Use the system¶