Docker and Docker Compose

Using Docker or Docker Compose on Windows and Linux is done via a command line shell and is almost identical on both platforms. You can use PowerShell or Command Prompt on Windows and a shell like bash or zsh on Linux. Refer to DeepHub System Prerequisites for details.

Using Docker or Docker Compose

We recommend using Docker Compose because this way you will get a completely configured “system” consisting of the DeepHub®, the DeepHub® UI and a containerized web server, acting as a reverse proxy, to simplify the overall usage and interaction of these components.

We provide a Docker Compose file that configures the necessary orchestration between these three containers. Refer to the next section in this documentation concerning more details on this.

Nevertheless, you are able to pull just the Docker container that you need instead of all three.

docker pull flowcate/deephub:<tag of release you want to pull>

Note

The DeepHub® itself, as well as the corresponding DeepHub® UI, are available at the official docker repository here: Flowcate@docker.

Getting the Latest Docker Compose File

We provide a docker-compose.yml file and additional configuration files for orchestration of the DeepHub® itself, as well as the corresponding DeepHub® UI, in our Github repository: deephub-basic-setup by Flowcate@github.

We recommend creating a dedicated local directory on your filesystem where you store the docker-compose.yml and the aforementioned configuration files which is what happens if you use git clone to pull the complete repository.

The DeepHub® needs to create some additional files during operations and writes them to directories mounted from your host filesystem. This is done relative to the location of the docker-compose.yml file and will therefore happen within some of the directories that are part of the deephub-basic-setup repository.

Details of the Docker Compose file explained

Our Docker Compose file consists in essence of three “services”, as they are called:

  • “deephub”

  • “deephub-ui”

  • “deephub-apache”

Each of them corresponds to exactly one docker container. The names already indicate to which ones. Within each service section, docker specific details can be configured as well as environment variables for the processes running within a container. Let’s pick an example section:

deephub:
  image: flowcate/deephub:latest
  container_name: 8081-deephub
  restart: unless-stopped
  read_only: true
  logging:
    driver: "json-file"
    options:
      max-file: "2"
      max-size: "10m"
  environment:
    - DEEPHUB_PORT=7081
    - DEEPHUB_CORS=true
    - DEEPHUB_LICENSE_KEY=50f7eb6d-4b4c-4a7b-8d60-0c439328214c
    - SQLITE_TMPDIR=/data
  ports:
    - "7081"
  volumes:
    - "./hub-data/:/data"
  networks:
    - deephub-net

First of all, there is the name of a service. In this case it is “deephub”. Next are docker specific parameters like docker image name and tag, name of the container that is build from it, the restart policy and whether the container should run in read-only mode which means that no process running within the container is allowed to write to the docker container’s own filesystem. Next there are docker parameters for logging.

The environment key starts the section containing the environment variables that are made available within the docker container. You’ll notice DeepHub-specific ones, of course, like e.g. the port on which the DeepHub should listen. All DeepHub-specific environment variables start with the capital letters DEEPHUB, an underscore, and the capital spelling of the parameter as specified in the “Server Configuration” section further down this documentation. Note the SQLITE_TMPDIR variable: it is necessary to specify a path to which the SQlite DB can write temporary information. The path has to be a known path from the point of view of the container and has to be writable.

Note concerning the port number specified: this is the port number within the docker container. It is not necessarily identical to the port on which the process is reachable from outside of the container though. It is the following section called ports that make this port available from the outside. In this case, it is the same port as the DeepHub process uses within the container. Instead of that simple entry, a “port mapping” could have been specified. The latter is nothing more than specifying the outside port number and the corresponding inside port number to which it should be mapped. For more details please refer to the Docker and Docker Compose documentation.

The volumes section is important to mention because it presents the mapping/mounting of external directories to container internal ones. In the example above, the external/host directory called “hub-data”, relative to the location of the docker-compose.yml, is mapped to the absolute path /data within the container. The read-only container can write to this external directory in case the user and group permissions on the host filesystem are set appropriately.

Start a DeepHub®

  • Open a shell (PowerShell or Command Prompt on Windows, a terminal on Linux)

  • Change to the directory where your docker-compose.yml file resides. Docker Compose won’t work if invoked outside this directory.

  • Invoke Docker Compose. It will take a few minutes to download the Docker images and set up the DeepHub®.

Example:

cd <directory where the docker-compose.yml is>
docker-compose up -d

Note

On Linux, it may be necessary to call docker-compose as superuser via the sudo command.


Now you have your own running DeepHub® instance that can be accessed with any modern web browser at the address: http://localhost:8081

../_images/deephub-ui.jpg

To complement the DeepHub UI shown above, you may also make API calls to the DeepHub REST API while running the DeepHub locally. This can be done with a tool such as Postman or cURL.

The containerized web server included in the Docker Compose bundle acts as a reverse proxy - forwarding requests to either the DeepHub UI or DeepHub containers.

To interact with the REST API, you will need to use the following baseURL: http://localhost:8081/deephub/v1

For example, retrieve an array of all zones:

curl http://localhost:8081/deephub/v1/zones/summary | json_pp

Stop a running DeepHub®

Please make sure you are in the same directory where you invoked docker-compose.

To stop a running DeepHub®, execute ‘docker-compose down’. This ensures the running DeepHub® is stopped and allows the user to modify the configuration data.

Example:
  cd <directory where the docker-compose.yml is>
  docker-compose down

Note

On Linux, it may be necessary to call docker-compose as superuser via the sudo command.