Quick Start

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

Docker

The Semantic Objects use Docker and Docker containers for all of their services. All of them are published in the Ontotext 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 Semantic Objects 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 Semantic Objects, GraphDB, and Workbench containers on a single machine.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
version: '3.6'

services:

  semantic-objects:
    image: ontotext/platform-soaas-service:4.0.4
    restart: always
    depends_on:
      - graphdb
    environment:
      SOAAS_JAVA_OPTS: >-
        -Xmx2g -Xms512m
      application.name: soaas
      sparql.endpoint.address: "http://graphdb:7200/"
      sparql.endpoint.repository: "soaas"
      storage.location: "/var/lib/soaas"
      platform.license.file: "/PLATFORM.license"
    volumes:
      - soaas_data:/var/lib/soaas
      # - /path/to/the/file/license_name.license:/PLATFORM.license:ro
      # Example for license saved in a folder 'license', created where the docker-compose file is saved
      #- ./license/EVALUATION_ONTOTEXT_PLATFORM_expires-dd-mm-yyyy.license:/PLATFORM.license:ro
    ports:
      - "9995:8080"

  graphdb:
    image: ontotext/graphdb:10.2.3
    restart: always
    ports:
      - "9998:7200"
    environment:
      GDB_JAVA_OPTS: >-
        -Xmx2g -Xms2g
        -Denable-context-index=true
        -Dentity-pool-implementation=transactional
        -Dhealth.max.query.time.seconds=60
        -Dgraphdb.append.request.id.headers=true
        -Dgraphdb.workbench.importDirectory=/opt/graphdb/home/graphdb-import
    volumes:
      - graphdb_data:/opt/graphdb/home
      # GraphDB license can be mounted like so:
      # - /path/to/the/file/graphdb.license:/opt/graphdb/home/conf/graphdb.license:ro
      # Example for license saved in a folder 'license', created where the docker-compose file is saved.
      # Note that the license must be named graphdb.license!
      #- ./license/graphdb.license:/opt/graphdb/home/conf/graphdb.license:ro

  workbench:
    image: ontotext/platform-workbench:4.0.2
    restart: always
    depends_on:
      - semantic-objects
    ports:
      - "9993:3000"
    environment:
      SOAAS_ENDPOINT: "http://semantic-objects:8080"

volumes:
  soaas_data:
  graphdb_data:

Note

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

The Ontotext Semantic Objects are 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.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
version: '3.6'

services:

  semantic-objects:
    image: ontotext/platform-soaas-service:4.0.4
    restart: always
    environment:
      SOAAS_JAVA_OPTS: >-
        -Xmx2g -Xms512m
      application.name: soaas
      sparql.endpoint.address: "http://<addressOfGraphDB>:7200/"
      sparql.endpoint.repository: "soaas"
      storage.location: "/var/lib/soaas"
      platform.license.file: "/PLATFORM.license"
    volumes:
      - soaas_data:/var/lib/soaas
      # - /path/to/the/file/license_name.license:/PLATFORM.license:ro
      # Example for license saved in a folder 'license', created where the docker-compose file is saved
      #- ./license/EVALUATION_ONTOTEXT_PLATFORM_expires-dd-mm-yyyy.license:/PLATFORM.license:ro
    ports:
      - "9995:8080"

  workbench:
    image: ontotext/platform-workbench:4.0.2
    restart: always
    depends_on:
      - semantic-objects
    ports:
      - "9993:3000"
    environment:
      SOAAS_ENDPOINT: "http://semantic-objects:8080"

volumes:
  soaas_data:
  graphdb_data:

To configure the Semantic Objects 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 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"

The above configurations limit access control to the database to a single user that needs to have access to all repositories that are to be exposed via the GraphQL interface. If more fine-tuned access control is required, you need to use OpenID (OIDC) authorization for GraphDB and/or the Semantic Objects.

For information on how to enable and configure OpenID in GraphDB, see the GraphDB documentation on Access Control with OpenID authentication.

On the Semantic Objects side, the following configurations must be set:

  • sparql.endpoint.httpHeadersPassthrough: Authorization
  • security.jwks-uri: http://<path-to-jwks-json>

The first configuration will enable passing the Authorization HTTP header from the GraphQL request to GraphDB. This way, GraphDB can also authenticate the request and check if the authenticated user has access to the target repository.

The second one is needed to configure the Semantic Objects service to read and validate the OpenID-compatible tokens. This configuration is only necessary if Semantic Objects security is enabled. If it is disabled, authentication and authorization will be applied only on the GraphDB side.

Note

If authentication and authorization are per-repository, all users must either have access to the configured system repository (otp-system), or a dedicated user must be configured for this with the following configurations:

  • soml.storage.rdf4j.username
  • soml.storage.rdf4j.credentials

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

cURL

cURL is required only if you intend to use system console to create repositories and load data into GraphDB, manage a Semantic Objects schema, as well as perform GraphQL queries. All of these actions can be executed using the 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, the 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 GraphDB 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 GraphDB 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 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:

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

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
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6ImJNODctcWV3SldXTWRMRjIzNUtXUmluTlp4TDA0ZngzIn0.eyJhdWQiOiI2NzJjYTdiMy1jMzcyLTRkZjMtODJkOC05YTFhMGQ3ZDY4YzEiLCJleHAiOjE3MjkyNDk4MTksImlhdCI6MTY5ODE0NTgxOSwiaXNzIjoic3dhcGktcGxhdGZvcm0ub250b3RleHQuY29tIiwic3ViIjoiZTlmOWQzNGQtZThmMS00ODM1LTlkMzAtOWRjNmU5YjQ4ZmMzIiwianRpIjoiODZjNTIzYzEtYzQzNC00MWZiLWFkOTctYWU2MDY5MjgxYWM4IiwiYXV0aGVudGljYXRpb25UeXBlIjoiUEFTU1dPUkQiLCJlbWFpbCI6InJlYWRvbmx5dXNlckBleGFtcGxlLmNvbSIsImVtYWlsX3ZlcmlmaWVkIjp0cnVlLCJwcmVmZXJyZWRfdXNlcm5hbWUiOiJSZWFkT25seVVzZXIiLCJhcHBsaWNhdGlvbklkIjoiNjcyY2E3YjMtYzM3Mi00ZGYzLTgyZDgtOWExYTBkN2Q2OGMxIiwicm9sZXMiOlsiUmVhZE9ubHkiXSwiZGF0YSI6e319.yVwuhsZQQgbk6ASaaA5iS2z_E7ThqPpMtYKfxjVcND8
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 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 Semantic Objects 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

Docker Compose - Additional Services

With this extended docker-compose-all.yaml file, you can enable the Semantic Objects together with security, federation, monitoring & the Semantic Search.