TethysDash System installation via Docker¶
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.
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:
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:
||A brief version of these instructions|
||Required environment variables|
||Optional list of links to include in Dash's dropdown menu|
||Optional list of stations for the map|
||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:
||Desired password for the Postgres super user.|
||Desired password for the 'tethysdash' user in Postgres.|
||Postgres data directory.|
||Host port where the Postgres service will be exposed. Useful to be able to connect to the 'tethysdash' database from outside the container.|
||Directory containing TethysDash.conf.|
||Directory for the data directly managed by TethysDash.|
||(OPTIONAL) Directory to map the TethysDash log location.|
||Directory under which all email logs will be stored.|
||Host port where the TethysDash service will be exposed.|
||Directory containing the LRAUV configuration and mission git clones.|
The vehicle configuration and mission git clones
must be named
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.
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
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¶
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.
volumessections establish a mapping between host directories/files and corresponding directories/files in the containers.
portssections establish a mapping between host ports and corresponding ports in the containers.
environmentsections allow to define environment variables for the corresponding containers.
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 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
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
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 stop tethysdash $ docker start tethysdash $ docker restart tethysdash
Enabling a new version of a Docker image
Please see the releases page, and get in touch if you have any questions.
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
Please check with your sysadmin.