Docker Compose

The Ontotext Platform is shipped as a Docker image and can be deployed with Docker compose along with all dependent components and services. This page contains an example deployment with Docker compose that will deploy the Platform with security, monitoring, and example data provisioning.

Prerequisites

Environment

This environment file is used to define service configurations. It is interpolated by Docker Compose when deploying the Platform. Use it to customize the deployment.

It contains several file path properties that refer to the ~/.platform/ folder. You should either place these files there, or update the properties:

Note

We recommend using absolute paths, especially when running Docker in Windows. The ~/.platform/ path will resolve to C:\Users\<USER>\.platform folder when running Docker on Windows.

  • KONG_DECLARATIVE_CONFIG_PATH - Path to a configuration file for Kong’s declarative configuration. You can tune this file according to your needs, but by default it exposes most services. See the example kong.yaml.

  • PLATFORM_LICENSE_PATH - Path to a license file that will be used by the Semantic Objects Service. This license will be provided to you by our sales team.

  • GDB_LICENSE_PATH - Path to a license file that will be used by the GraphDB service, to be obtained from our sales team also.

  • TELEGRAF_CONFIG_PATH - Path to a Telegraf configuration file defining input and output plugins. Tune according to your monitoring needs. See the example telegraf.conf.

The following file paths are required only if you use the provisioning compose:

  • GDB_REPO_TTL_PATH - Path to a repo configuration TTL. Used when provisioning GraphDB. See the example repo-config.ttl.

  • SOML_SCHEMA_PATH - Path to a SOML schema to be uploaded and bound in the Semantic Objects Service. See the example schema.yaml .

  • OCPTL_CONFIG_PATH - Path to an opctl CLI configuration that configures the security provisioning. See the example opctl.yaml.

Deployment

After the environment is prepared, use this docker-compose.yaml configured to deploy the Platform with security and monitoring.

To deploy the Platform, execute the following shell command while in the directory with the Docker compose file:

docker-compose up -d

Note

It may take a while for the services to become available.

To stop and remove all Platform services, use:

docker-compose down

To remove all persisted data as well, use:

docker-compose down --volumes

API Gateway

When deployed, you can access Ontotext Platform services from the API gateway. By default, it deploys on http://localhost:8000.

  • GraphQL endpoint: http://localhost:8000/graphql

  • GraphDB Workbench: http://localhost:8000/graphdb

  • OTP Workbench: http://localhost:8000/workbench

  • FusionAuth: http://localhost:8000/admin

  • Grafana: http://localhost:8000/grafana

Note

By default, Kong listens on http://localhost:8000 and http://localhost:8443. If necessary, you can update those in the compose file but make sure to update the .env file, as well as opctl.yaml and kong.yaml.

Provisioning

After deploying the Platform, you can either manually configure the security and upload SOML schemas or deploy it along with the provisioning Docker compose.

You can provision the following:

  • GraphDB default repository

  • Semantic Objects Service SOML schema

  • Platform security and GraphDB security

Note

See the OPCTL documentation on preparing an OPCTL CLI configuration file or modifying the example configuration from this page.

This docker-compose-provision.yaml specifies the provisioning services. Once they complete, they will exit and will not restart.

To deploy the Platform with the provisioning services, use the following shell command:

docker-compose -f docker-compose.yaml -f docker-compose-provision.yaml up -d

Note

The provisioning will not run on consecutive deployments in order to protect the data.

To stop and remove all Platform services, use:

docker-compose -f docker-compose.yaml -f docker-compose-provision.yaml down

Hint

The provisioning Docker compose does not support uploading data into GraphDB. Follow Star Wars RDF Data to download example data and upload it.

To remove all persisted data as well, use:

docker-compose -f docker-compose.yaml -f docker-compose-provision.yaml down --volumes

Preloading

The Platform has a preload mechanism for schemas. This is an alternative to the provision-soaas-soml described above. It is possible to specify a SOML schema and have it load and bind during startup. The schema will be preloaded if:

  • There are no other schemas already bound.

  • The schema is valid.

  • No other schemas with the same ID already exist.

This mechanism makes first-time loading of the Platform more straightforward. Once you have the schema preloaded, you can drop the line from the configuration, but it is not necessary - the preload file will not overwrite previously stored schemas.

You can use preloading by adding a new variable to the environment of the Semantic Objects Service.

semantic-objects:
  ...
  environment:
    ...
    soml.preload.schemaPath=/etc/soml/schema.yaml
    ...
    volumes:
      - ${SOML_SCHEMA_PATH}:/etc/soml/schema.yaml
...

Then, if you want to also use the provisioning mechanism described above for the GraphDB and security components, you will need to drop the provision-soaas-soml service.

Apollo Gateway Federation

Ontotext Platform provides GraphQL federation with Apollo Federation Gateway. See the GraphQL Federation documentation for more information.

To deploy the Platform with federation, you can download and use the following example configurations:

Then update the .env file to point to the updated configurations. For example, if you place the files in ~/.platform/, update it like so:

KONG_DECLARATIVE_CONFIG_PATH=~/.platform/kong-federation.yaml
TELEGRAF_CONFIG_PATH=~/.platform/telegraf-federation.conf
OCPTL_CONFIG_PATH=~/.platform/opctl-federation.yaml

Note

We recommend using absolute paths, especially when running Docker in Windows. The ~/.platform/ path will resolve to C:\Users\<USER>\.platform folder when running Docker on Windows.

After preparing the configurations, execute the following shell command to deploy Ontotext Platform with federation:

docker-compose -f docker-compose-federation.yaml up -d

You can also deploy the provisioning, use:

docker-compose -f docker-compose-federation.yaml -f docker-compose-provision.yaml up -d

You can now access the OTP Workbench on the same address http://localhost:8000/workbench and all GraphQL queries will be against the Apollo gateway.

To stop and remove all components, use:

docker-compose -f docker-compose-federation.yaml -f docker-compose-provision.yaml down

To remove the persisted data as well, use

docker-compose -f docker-compose-federation.yaml -f docker-compose-provision.yaml down --volumes