How to use the Hets Docker Container

Status 02.12.2019

There are two options to use the Hets Docker Container:

Use a standalone Hets Docker Container, this is just the hets-server executable running in a Docker environment
Use a Hets Docker Container with a PostgreSQL database running aswell

For both options Docker CE (Community Edition) must be installed on your system, please follow the instructions for your operating system: https://docs.docker.com/install/

1. Hets standalone container

To use Hets as a standalone container you need to pull the container from Docker hub first:

docker pull spechub2/hets

This pulls the latest tagged version of the Hets Docker image.

If you wish to use a specific version of Hets, see the supported tag list on Docker hub.

Starting the container

To start the container execute the following commands.

First create a directory called hets_data in your current working directory otherwise starting the container will fail:

mkdir hets_data

Starting the container creates a bind mount to hets_data in your current working directory.

Execute the following command to start the container:

docker run -d \
-p 8000:8000 \
--mount type=bind,source=$PWD/hets_data,target=/data/ \
--name="hets_docker_container" \
--rm \
spechub2/hets:latest

(Actually, you can replace $PWD/hets_data with any folder of your convenience.)

Hets is now running as a server with port 8000 exposed to the host. REST calls are now possible.

A graphical user interface (GUI) is reachable in your browser under the address: http://localhost:8000

Stopping the container

To shutdown the container run:

docker stop hets_docker_container

2. Hets container with a PostgreSQL database

To use this variant of Hets you need to install docker-compose on your system, please follow the installation instructions for your operating system: https://docs.docker.com/compose/install/

Two images will be used, one image for the Hets container and one for the PostgreSQL container. Both are automatically pulled from Docker Hub if not available on your system.

Prepare and start the containers

Note: All docker-compose commands must be executed in the directory with the docker-compose.yml file.

Prepare the launch directory

A docker-compose.yml file has been created and can be found in the Hets Repository under Docker/docker-compose.yml.

Place it in the directory in which you wish to start the containers. In this directory needs to be a directory hets_data working in the same way like the standalone Hets Container.

Configuring the docker-compose.yml

Before starting you need to define where the secret files containing the PostgreSQL username and passwords.

This can be configured in the docker-compose.yml:

secrets:
  db_password:
    file: {path-to-your-postgres-password-file}
  db_username:
    file: {path-to-your-postgres-username-file}

Replace the corresponding section in the example file with the paths pointing to the files, the paths can be absolute or relative.

Each file must only contain the corresponding information (like the PostgreSQL password).

First run of the PostgreSQL container

If you start the PostgreSQL container for the first time or removed it's volume you need to execute the following command for Hets to work with the database:

docker exec -t docker_hets_1 hets-server --output-types=db --database-config=/etc/hets_db_postgresql.yml --database-subconfig=production --logic-graph

Starting the containers

To start up both containers in detached mode run the following command:

docker-compose up -d

Hets is now running as a server with port 8000 exposed to the host. REST calls are now possible.

A graphical user interface (GUI) is reachable in your browser under the address: http://localhost:8000

Stopping the containers

To shutdown the containers run:

docker-compose down

Backup and restore the PostgreSQL database

Backup

The PostgreSQL container uses a Docker volume which is persistent as long as you let the Docker deamon handle the data.

But you can create a dump of the hets database and store it on you system.

For this run:

docker exec -t docker_db_postgresql_1 pg_dump hets -c -U postgres > {your-hets-database-dump}.sql

Restore

You can restore the hets database from a dump stored on your system.