Quick Start

Install and start the Platform in less than 5 minutes following the steps below.

Docker

The Ontotext Platform uses Docker and Docker containers for all of its services. All of them are published in Ontotext’s Docker hub. You will need to install the Docker daemon on the machine on which you will be running the service.

Please follow the Docker installation guide.

Docker Compose

The Ontotext Platform components can be run using a Docker Compose configuration on your developer machine.

You will need to install Docker Compose on the machine on which you wish to run the service.

Follow the Docker Compose installation guide.

A docker-compose.yaml configuration will download and start the important containers on a single machine.

Note

When deploying the Ontotext Platform on an environment different from localhost, you need to set the environment variable GRAPHQL_ENDPOINT to "http://ip-of-deployment-host:9995/graphql".

Below is a list of available alternative Docker Compose files that you can use depending on which service(s) you want to enable.

Deployed services Docker Compose file
SOaaS, GraphDB, Workbench docker-compose.yaml
Search, SOaaS, GraphDB, Workbench, Elasticsearch, Kibana search-docker-compose.yaml
Apollo Gateway, SOaaS, GraphDB, Workbench graphql-federation-docker-compose.yaml
Workbench workbench-docker-compose.yaml
Apollo Gateway docker-compose-apollo.yaml
Kong, FusionAuth, Fusion DB, Fusion Search kong-fusionauth-docker-compose.yaml
GraphDB graphdb-docker-compose.yaml
Kong, SOaaS, GraphDB, Workbench, FusionAuth, Fusion DB, Fusion Search, Grafana, InfluxDB, Telegraf docker-compose-all.yaml

The Ontotext Platform is available under a commercial time-based license. To obtain an evaluation license, please contact the Ontotext team and see the documentation on Setting up Licenses.

Once you have obtained the license, you can either:

Note

If you have a pre-existing installation of GraphDB and want to use it instead of setting up a new instance, you can use the following docker-compose-remote-graphdb.yaml

To configure the Ontotext Platform to work with an existing/remote GraphDB, you need to set the GraphDB address in the sparql.endpoint.address: environment variable. Please note that the Semantic Objects Service must be able to access the provided address set to the configuration soml.storage.rdf4j.address.

If GraphDB has security enabled, you need to provide the username and password with the following environment variables in the semantic-objects service section:

  • sparql.endpoint.username: "yyyyyyy"
  • sparql.endpoint.credentials: "xxxxxxxxx"

If you want to deploy GraphDB in a cluster topology, follow the GraphDB cluster topologies instructions.

Curl

Curl is required only if you intend to use system console to create repositories and load data into GraphDB, manage SOaaS schema, as well as perform GraphQL queries. All of these actions can be executed using the Platform Workbench.

Please follow the cURL installation guide.

Start the Service

Start the docker containers using:

docker-compose -f /path/to/your/docker-compose.yaml up -d

Hint

If you are using pre-existing/remote GraphDB, the command should be:

docker-compose -f /path/to/your/docker-compose-remote-graphdb.yaml up -d

If you have problems with old containers, consider using the --force-recreate flag, e.g., docker-compose -f /path/to/your/docker-compose.yaml up -d --force-recreate.

You can check the running containers using the following docker command:

docker ps

It should include Semantic Objects Service, OTP Workbench and GraphDB.

Initialize GraphDB

  1. If your GraphDB distribution is an Enterprise edition like in the example above, you will need to provide a license. You can do it through the Workbench using http://localhost:9998/. See the official documentation on Setting up Licenses.

    Hint

    Alternatively, the license can be provisioned by mounting it in the Docker container in the /opt/graphdb/dist/conf/graphdb.license path.

    If you are using a pre-existing/remote GraphDB you can proceed directly with the repository creation.

  2. Once the license is provisioned, you need to create a repository. First, download the repo.ttl RDF dataset, which contains configurations for a repository named soaas.

  3. Upload it via the GraphDB Workbench following the instructions for Creating a repository.

    Alternatively, you can also upload it using the following cURL command:

    curl -X POST -H "Content-Type: multipart/form-data" -F "config=@repo.ttl" http://localhost:9998/rest/repositories/
    

Hint

A repo can be automatically initialized by GraphDB if repo.ttl is mounted in the Docker container under the /opt/graphdb/dist/data/repositories/soaas/config.ttl path.

Put Star Wars Data into GraphDB

  1. Download the starwars-data.ttl RDF dataset.

    It describes Star Wars, films, starships, characters, etc. You can find more details about this dataset here.

  2. Upload it via the GraphDB Workbench following the instructions for Loading data from a local file.

    Alternatively, you can also upload it using the following cURL command:

    curl -X POST -H "Content-Type:application/x-turtle" -T starwars-data.ttl http://localhost:9998/repositories/soaas/statements
    

Define Star Wars Semantic Objects

  1. Download the Semantic Object schema.yaml.

    It describes the Semantic Object mapping to Star Wars RDF, and is then used to generate a GraphQL schema for querying the Star Wars data.

  2. Load the Semantic Objects schema from the Platform Workbench on http://localhost:9993/ following the instructions for Uploading Schema Wizard.

    Alternatively, you can also load it using the following cURL command:

    curl -X POST -H "Content-Type: text/yaml" -H "Accept: application/ld+json" -T schema.yaml -H "X-Request-ID: GettingStartedTx01" http://localhost:9995/soml
    
  3. Activate (bind) this schema instance in order to generate a GraphQL schema. You can do this from the Workbench by following the Upload Schema Wizard steps or from the Manage Schema page.

    Alternatively, you can also activate it using the following cURL command for the Semantic Objects Service:

    curl -X PUT -H "X-Request-ID: GettingStartedTx02" http://localhost:9995/soml/swapi/soaas
    

    If your deployment includes the Semantic Search Service you should also activate it using the following cURL command:

    curl -X PUT -H "X-Request-ID: GettingStartedTx03" http://localhost:9980/soml/swapi/search
    

Run a Star Wars GraphQL Query

The following query gets all planets that contain “Tatooine” ordered in ascending order. Each resident is ordered by height and name.

Loading...
https://swapi-platform.ontotext.com/graphql
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IlVWWHMyZ2hidFhBSUtyc2V5QnduTVYzR0dBSEZaRzMwIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE2NjAyOTExMDksImlhdCI6MTU5NzIxOTEwOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiM2I2YzA3MjktNTJiMC00NDk4LWIxZGUtOTE4YjZjMTU4N2M5IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXX0.KIoFrune5hKqkHDr4BgRbaHZyrkoYoCq9SPBuN9NLxE
true
query Tatooine { planet( orderBy: {name: ASC} where: {name: {IRE:"tatooi"}}) { id name type climate resident(orderBy: {height: ASC, name: DESC}) { name starship{ id name type passengers } type mass height film { name } hairColor vehicle { name } } } }

You can execute the query by accessing the Platform Workbench GraphiQL Playground on address http://localhost:9993/graphql.

An equivalent cURL request looks like this:

curl 'http://localhost:9995/graphql' \
      -H 'Accept: application/json' \
      -H 'Content-Type: application/json' \
      --data-binary '{"query":"query Tatooine { planet( orderBy: {name: ASC} where: {name: {IRE:\"tatooi\"}}) { id name type climate resident(orderBy: {height: ASC, name: DESC}) { name starship { id name type passengers } type mass height film { name } hairColor vehicle { name }}}}","variables":null,"operationName":"Tatooine"}' \
      --compressed

Stop the Service

Stop and remove all Platform docker containers using:

docker-compose -f /path/to/your/docker-compose.yaml down

To remove the volume data as well, use:

docker-compose -f /path/to/your/docker-compose.yaml down --volumes