Direct set-up

Note

As we are currently focusing on the Docker-based installation, the instructions below may be incomplete/out-of-date.

The following are instructions to install and execute the TethysDash application.

TethysDash binary distribution

The binary distribution of the TethysDash system consists of the following:

• TethysDash-x.y.z.zip Contains the TethysDash application itself (backend and front-end):

  • template.TethysDash.conf A template for the configuration of the application
  • TethysDash.war The executable WAR file

• dash3-x.y.z.zip Contains the Dash3 front-end

• tdusr-x.y.z.zip Contains the front-end for user account management:

  • config.js Javascript file with the configuration for tdusr
  • ... Files to be deployed at the root / of the target URL location

Requirements

Git and vehicle configuration and mission repositories

TethysDash accesses mission and configuration files from two indicated Git repositories:

• vehicle configurations
• mission files

Vehicle deployments are tied to Git tags, which allows TethysDash to keep track of available missions and capabilities of each deployed vehicle.

Please see the "LRAUV Application" documentation for details about these artifacts.

Database

TethysDash uses PostgreSQL as its database server. We have successfully been using PostgreSQL version 9.4.

Email

• Email server. An email server with IMAP and SMTP capabilities is needed for managing emails to and from TethysDash. A dedicated email address is recommended since TethysDash will be managing the inbox and routing all incoming mail to designated folders (which it will create).

  Hint

  You may want to send incoming mail from Iridium and Argos to an email list or alias (such as tethys_incoming@my.server.com) so that additional users can configure the list/alias to temporarily "listen in" on emails.

• JavaMail library. At runtime TethysDash needs the JavaMail library to perform email related operations. This library can be downloaded from java.net. TethysDash currently uses version 1.5.2 of this library.

Web application server

TethysDash runs as a web application deployed on an Apache Tomcat container. You need ability to start/stop/restart this container.

Use the latest 7.0 version from https://tomcat.apache.org/.

Other servlet containers might also be work but only Tomcat has been tested.

Instructions

Database setup

• Create a database with name "tethysdash", and a user with name "sa":
  $ createdb tethysdash; createuser sa

  These names are configurable, see below.

• Grant user "sa" all permissions on the "tethysdash" database:
  # grant all on database tethysdash to sa;

Web application server

We will assume you have Tomcat installed under /opt/tomcat7/.

• Place a copy of the JavaMail library under /opt/tomcat7/lib/

• Edit /opt/tomcat7/conf/server.xml to make sure the URIEncoding="UTF-8" setting is associated to the defined connectors. For example:

      <Connector port="8080" protocol="HTTP/1.1"
                 URIEncoding="UTF-8"
                 connectionTimeout="20000"
                 redirectPort="8443" />
  
      ...
  
      <Connector port="8009" protocol="AJP/1.3"
                 URIEncoding="UTF-8"
                 redirectPort="8443" />
  

• Under /opt/tomcat7/webapps/ create a file TethysDash.conf as a copy of the provided template.TethysDash.conf file. Ensure that the user account under which Tomcat is run has read permission to /opt/tomcat7/webapps/TethysDash.conf.

TethysDash configuration

/opt/tomcat7/webapps/TethysDash.conf is the primary configuration file for TethysDash. The following explains the configuration properties that are required and also those that can be overwritten in a typical installation.

Database

db {
  # Connection:
  javax.jdo.option.ConnectionURL        = "jdbc:postgresql://localhost:5432/tethysdash"
  javax.jdo.option.ConnectionUserName   = "sa"
  javax.jdo.option.ConnectionPassword   = "the-password"
}

Git access to configuration and mission files

git {
  privateKey = "/path/to/private_rsa_key"
  knownHosts = "/path/to/known_hosts"

  configRepo  = "/path/to/lrauv-config/.git"
  missionRepo = "/path/to/lrauv-mission/.git"
}

Miscellaneous settings

# Where to save data - should be an archived, read/writable path
data.path = "/data/"

# External URL of this web application, for links sent in e-mails.
urlExternal = "http://my.server.com/TethysDash"

# Which vehicle to show when no vehicle has been selected yet
defaultVehicle = "tethys"

User authentication

auth {
  # A strong password used to generate/verify authentication tokens
  secret = "..."

  # Token expiration. User will be logged out after this period of inactivity.
  # Use a suffix to indicate units, eg., "30m", "24h", "10d".
  tokenExpiration = "12h"
}

Administrative

Properties in the admin section are for administrative purposes. At least a valid email address is required for the admins entry. The other entries are optional.

admin {
  # comma separated list of emails that will be automatically granted "admin" role upon account creation
  admins = "foo@example.net"

  # comma separated list of emails that will be automatically granted "operator" role upon account creation
  #operators =

  # comma separated list of emails to be notified when a user account has been created
  #accountCreationRecipients =
}

Email settings

mail {
  # Name of sender used in outgoing e-mails
  title = "Tethys Dashboard"

  # Default server to use for both email send and receive
  host = "mail.my.host.com"

  imap {
    # Server to use for email receive (overrides mail.host)
    host = "imap.my.host.com"

    # Username for IMAP connection
    user = "myUsername"

    # Password for receiving email
    password = "myImapPassword"
  }

  smtp {
    # Server to use for email send (overrides mail.host)
    host = "smtp.my.host.com"

    # Username for SMTP connection
    user = "myUsername@my.host.com"

    # Password for sending email
    password = "mySmtpPassword"
  }
}

# Where to store e-mail activity logs
emailLogPath = "/var/www/emaillogs"

Iridium system

sbd {
  # Regex for recognizing e-mails from Iridium system
  from.regex = "sbdservice@sbd.iridium.com"

  # Regex for recognizing relevant e-mails from Iridium system
  subject.regex = "SBD Msg From Unit: ([\\d]+)"

  # Where to send e-mails to Iridium system
  outgoing.address = "data@sbd.iridium.com"

  # (optional) For e-mails to Iridium system, CC this comma-separated list of email addresses
  #outgoing.cc = "foo@example.net"

  # (optional) For e-mails to Iridium system, BCC this comma-separated list of email addresses
  #outgoing.bcc = "foo@example.net"
}

Argos system

argos {
  # Regex for recognizing e-mails from Argos system
  from.regex = "argosdirect@clsamerica.com"

  # Regex for recognizing relevant e-mails from Argos system
  subject.regex = "(D[\\w]+) FOR PGM ([\\d]+)"
}

Asynchronous notifications

Besides email, TethysDash can also send notifications using two possible mechanisms, Pusher and Slack. Both of these are optional.

• Pusher. Assuming you already have a Pusher account, go to https://dashboard.pusher.com/ and create an application for TethysDash purposes. Take note of the credentials of the created application: app_id and key, and secret, which you will need to indicate in the async.pusher.url property.

  Your Pusher application key will also need to be specified in FleetStatus configuration.

• Slack. TethysDash uses this API to post notifications on a desired Slack channel. Create a Slack "webhook" and take note of corresponding URL.

Edit the async section in TethysDash.conf to specify the relevant properties as desired.

async {

  # pusher notifications, enabled if pusher.url is defined
  pusher {
    url = "http://???:???@api.pusherapp.com:80/apps/????"

    eventChannelName = "td-events"
  }

  # slack notifications, enabled if slack.webHook is defined
  slack {
    #webHook  = "https://hooks.slack.com/services/??/??/??"

    primaryChannel  = "#lrauvs"
    username = "??"
    dataLink = "http://okeanids.mbari.org/TethysDash/data"
  }
}

Running TethysDash

As a preparation to verify the initial execution of TethysDash, open a terminal session and run:

tail -f /opt/tomcat7/logs/catalina.out

This will show the main output from your Tomcat container.

Using another terminal session, place the provided TethysDash.war binary under the /opt/tomcat2/webapps/ directory.

If already running, your Tomcat container will automatically detect the new application, deploy it, and execute it. Otherwise, just start Tomcat to trigger the process.

Upon successful execution, the catalina.out output will look like this:

.. TODO...

At this point anyone whose email is listed in the admin.admins configuration property can go ahead and create their TethysDash account with the corresponding email address. They will automatically be granted the "admin" role, which is needed to manage the roles of other users as they create their own accounts.