How to install or upgrade the connector

Installing the TetraScience IDBS E-Workbook Connector involves four main steps: (1) creating a Docker volume, (2) downloading the Docker image, (3) creating the container with the appropriate volume mapping, and (4) starting the container. To do this, the system must have Docker.

📘

Host Connector on Data Hub

We recommend that the connector be installed on a TetraScience Data Hub. Both Docker and the AWS CLI v2 will be already installed if the system is also a TetraScience DataHub.

📘

Use Privileged Shell for CLI Commands

All of the commands should be done in a privileged shell.

macOS: If you are using an Administrator account, no additional action is required.

Linux: Run sudo su - to get a root login shell in which to execute the commands.

Starting the connector

The recommended deployment strategy for the Signals Notebook connector is to run it on a TetraScience DataHub. The connector is packaged as a Docker container so there are no software prerequisites when run on a DataHub.

Step 1: Load image from file

You should have received a download link from TetraScience. Download the file to the DataHub. To load it into Docker, run this shell command:

docker load --input ts-connector-signals-v1.0.0.tar

For the purposes of these instructions, we will use the filename ts-connector-signals-v1.0.0.tar and the image name ts-connector-signals:v1.0.0; if you have a different version, please substitute the correct values appropriately.

Step 2: Create volume

Although optional, we recommend using a Docker volume to store the SQLite databases so that configuration is automatically preserved during connector upgrades.

To create a volume, run this shell command:

docker volume create --driver local signals_connector_config

This creates a docker volume called signals_connector_config, which is typically located at /var/lib/docker/volumes/signals_connector_config in a standard Linux Docker installation.

When we create the container, this volume maps to /app/config within the container.

The connector uses this folder to store configuration, state, and logs in SQLite database files.

Step 3: Create container

To create the Docker container, you will use the following options.

• -p 3003:8080: forward traffic incoming on port 3003 on the host to port 8080 in the container
• --name=signals_connector: give the container a specific name of signals_connector
• -v signals_connector_config:/app/config: map /app/config in the container to use the Docker volume signals_connector_config set up in the previous step.

Create the Docker container with this shell command:

docker create -p 3003:8080 --name=signals_connector -v signals_connector_config:/app/config ts-connector-signals:v1.0.0

Step 4: Start container

To start the container you created:

docker start signals_connector

The connector will take some time (15 seconds is common in local testing; to become available once the container is started. If this is the first time starting the connector, you should be able to open up a browser to http://<hostname>:3003/ and set up the initial configuration. If you have previously configured the connector to use SSL, then go to https://<hostname>:3003/.