Quick Start¶

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.2
    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:

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:

• Move on to the next section and start the Semantic Objects and Set up a license from the Workbench using http://localhost:9993/, or
• Update the Semantic Objects volumes configuration in the Docker Compose file following the instructions for Setting up a license through a file.

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.

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

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/
   

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.

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.