Deploying a Secure Cluster with Docker

GraphDB can be deployed with Docker, allowing you to automate the deployment process and also ensuring that every single instance runs in the exact same conditions, regardless of the host machine.


Do not stop GraphDB while performing the following operations. If you terminate GraphDB inside the container, you will be ejected from it, as Docker containers are terminated when their entry point process - in this case, GraphDB - is terminated.

Deploying a secure cluster with Docker is a relatively straightforward process, only slightly more complex if you want to use encryption in transit with self-signed certificates.

In order to run a Docker cluster, your containers need to have different aliases. By default, each one of them will launch under localhost, making connection impossible. This is why you need to create a network first:

$ sudo docker network create gdb-cluster

Then create your containers with the command below, making sure that they have different aliases. Another important thing to keep in mind is that if the port you want to expose is different from 7200, you will also have to set a configuration parameter in GraphDB, making it run on a different port. Here is an example:

$ sudo docker run -p --network-alias master1 --network gdb-cluster --name graphdb-instance-name -t ontotext/graphdb:8.6.0-ee -Dgraphdb.connector.port=7300

Then set up the cluster as usual. If you want to connect to remote locations, instead of using localhost, you need to set the network alias. For example, the container created with the command above will be accessible at master1:7300 by all other containers within the gdb-cluster network.

If you want to enable and configure security, the easiest way is by supplying the configuration parameters. Here is an example of how to enable security:

$ sudo docker run -p --name graphdb-instance-name -t ontotext/graphdb:8.6.0-ee -Dsecurity.enabled=true

To create an external URL serving as an access point to GraphDB, use the graphdb.external-url parameter described in the GraphDB configuration properties.

If you want to use encryption in transit with certificates signed by a certificate authority, all you need to do is put them inside the container and set the relevant configuration properties.

Mounting the directory with the GraphDB certificates is achieved with the Docker -v flag. All other properties are set exactly as shown above, by directly entering them in the command line.

$ sudo docker run -v <your-local-keystore-file>:/root/.keystore -p --name graphdb-instance-name -t ontotext/graphdb:8.6.0-ee -Dsecurity.enabled=true -Dgraphdb.connector.scheme=https -Dgraphdb.connector.keystorePass=<secret> -Dgraphdb.connector.keyAlias=graphdb -Dgraphdb.connector.keyPass=<secret>

If you want to use self-signed certificates, you need to modify the existing container to include the certificate in the JVM trust store. This can be achieved by either patching an existing container, or creating a new one from scratch.

Since the first method requires less knowledge about Docker, we will cover this approach first. Note that in this case, you need to start and stop the container and a GraphDB instance at least once.

You can access the OS of a running container by running the following command:

$ docker exec -it graphdb-instance-name bash

Once you have access to the container, find the location where GraphDB is stored (by default it should be under /opt/graphdb), and execute the encryption in transit steps from this guide.

After that, you can safely exit and/or stop the container. At this point, you may also want to clean up your command history and any sensitive data you may have left, since everything that you do in the container will be committed in the new image.

Now that you have made these updates, commit the changes into a new image:

$ docker commit graphdb-instance-name your-company/your-updated-gdb-image:version1

You can now run your container as usual (making sure to supply the relevant configuration articles) by calling the new image. It should have the self-signed certificate added to the JVM.


Images created this way are not a completely “fresh” GraphDB installation - they will contain whatever was committed inside their parent container.

The second, cleaner method for working with self-signed certificates (and for making any changes in the container in general), is to edit the Dockerfile used to generate it. This is recommended if you are relatively comfortable using Docker, since it does not require that you start a container at least once, and does not lead to an image where the GraphDB instance has started at least once.

The Docker file for creating the GraphDB image is available on GitHub. Copy the Dockerfile and the Makefile to any directory on your machine.

In the Docker file, as part of the RUN command you need to add all commands that are needed to use self-signed certificates. You can also change any other GraphDB configurations.

Once you have edited the Dockerfile, run the following command:

$ sudo make ee VERSION=<version-of-graphdb-you-want>

It will create an image called ontotext/graphdb:<version-you-input>-ee. From here on, you can use this image when running your containers.