Docker Compose Template with Ontop and LodView

This repository contains a Docker Compose application providing a template for running the Ontop VKG engine side-by-side with LodView to provide URI dereferencing. For demonstration purposes, the application makes use of a simple PostgreSQL database with a company table with straightforward VKG mappings towards the Schema.org vocabulary. You may start from this template and adapt it to your database, ontology and mappings. Beware that URI dereferencing requires generated URIs to resolve to a server under your control, that you should configure separately to forward them to LodView, e.g., using Apache as reverse proxy (this part is not covered here and we skip it by simply generating localhost URIs).

Requirements

• Docker, version 17.09.0 or higher
• Docker Compose, version 1.17.0 or higher
• (optional) Ontop Protégé bundle to more easily browse and develop ontology and mappings

How to run the application

The application is configured and controlled using Docker Compose and/or Docker, as described next. Note that all the following commands reported here must be executed from the top-level directory of this repository containing docker-compose.yml.

Configuration. Before running it for the first time, the application may be configured to fit the local environment by either editing docker-compose.yml or, better, by editing the property values used therein and specified in a file .env. This .env file is not under version control (as it depends on your environment), but can be created starting from the template in .env.example. Besides .env, also file lodview/conf.ttl can be edited to tune LodView (not strictly required, defaults should be good). Here is the configuration process:

• create .env starting from the versioned template .env.example:

  cp .env.example .env

• edit file .env with the editor of your choice

  • you may change the variable USERPWD that will be used (together with USERID that you may change) by all the services of the application;
  • optionally, you may tune the other configuration variables, e.g., to change the ports used to avoid clashes with other services running on the machine

• edit file lodview/conf.ttl

  • refer to LodView documentation in the wiki and in the default conf.ttl file itself
  • editing this file is required in case you changed the setting LODVIEW_PORT=10000 in .env (must change the port similarly in conf.ttl)
  • editing this file is also required in case you deploy a reverse proxy (e.g., Apache) to expose LodView externally to handle external URI dereferencing requests (must change http://localhost:10000/ in this file to a the base URI used in your VKG mappings)

Execution. Use the following Docker Compose / Docker commands:

• to start the application, downloading / building the required images and containers if needed

  docker-compose up

  (note: may add option -d to run in background, in which case logs are not displayed to standard output but are still accessible via docker-compose logs)

• to test everything is running properly

  • open the Ontop portal at http://localhost:18080/ in a browser, click on tab Example query and run the query titled All companies, which should produce 3 results
  • click on any URI under column company, which should open the LodView visualization of that individual in another browser tab, including title, description, properties and image

• to stop the application, if running

  docker-compose down

• to stop the application, if running, and also clean any image / container / data associating to it (useful for cleaning up)

  docker-compose down -v --remove-orphans

  (note: the above command does not remove Docker images, such as the PostgreSQL one, which may result being unused after stopping and removing this application containers; to remove such images, add option --rmi all)

• to check the status of the containers forming the application

  docker-compose ps

• to check the logs of specific container(s) or of all containers (if no container name is supplied)

  docker-compose logs <container name 1> ... <contaner name N>

Services When running, the application exposes the following services:

• a PostgreSQL server with example company data, accessible using any PostgreSQL client such as psql, e.g. (assuming default admin username and password user and port 15432 were not changed):

  PGPASSWORD=user psql -h localhost -p 15432 -U user -d db

• a SPARQL endpoint backed by Ontop at URL http://localhost:18080/sparql (assuming default port 18080 is used), which may be accessed using any HTTP client, including SPARQL clients and tools using the standard SPARQL HTTP protocol. For instance, using curl:

  curl --request POST \
     --url http://localhost:18080/sparql \
     --header 'accept: application/json' \
     --header 'content-type: application/sparql-query' \
     --data 'SELECT * { ?s ?p ?o } LIMIT 5'

• a ReST API complementing the SPARQL endpoint with additional Ontop-specific services, such as the reformulate one that returns (without executing) the SQL translation of a SPARQL query (replace the SPARQL query accordingly):

  curl -G http://localhost:18080/ontop/reformulate --data-urlencode 'query=SELECT * { ?s ?p ?o }'

• a web portal UI at URL http://localhost:18080/ that users can open in a browser to enter and submit SPARQL queries and browse their results, also trying some predefined queries (configured in file ontop/vkg.toml)

• a LodView instance that will provide HTML / RDF representations of URLs of type http://localhost:10000/resource/... (which is the base URL used in VKG mappings of ontop/vkg.obda)

Repository organization

The repository is structured as follows:

• file docker-compose.yml defines the Docker Compose application forming the application;
• files .env.example (and its local version .env to be created) contain the environment properties used in docker-compose.yml to configure the application;
• directory db contains the SQL / bash scripts creating and populating the schema and data excerpt of the database; scripts are numbered and executed in alphanumeric order and script 20_data.sh populates the data of tables starting from compressed TSV files under db/data
• directory ontop contains the configuration files of the VKG:
  • vkg.ttl contains the VKG ontology in RDF Turtle format; it may be edited with any editor or Protégé;
  • vkg.obda contains the mappings between the ontology and the database, in ontop native .obda format; they may be edited either with a text editor or the ontop plugin of Protègè;
  • vkg.docker.properties contains the configuration properties required by ontop in order to access the database (e.g., host, port, username, password, database name, JDBC driver to use - no need to change them) inside the docker network;
  • vkg.properties is the properties file used by Ontop Protégé bundle. It is similar to vkg.docker.properties but with different JDBC URL so that it can be accessed from outside of the docker environment;
  • vkg.toml contains some configuration the predefined queries for the web portal UI;
• directory ontop/jdbc contains the PostgreSQL JDBC driver used by ontop to access PostgreSQL (no need to change it);
• directory ontop/bin contains additional scripts used to run ontop inside docker (e.g., script wait-for-it.sh to have ontop waiting for PostgreSQL to start).
• directory lodview contains the configuration for LodView
  • lodview/Dockerfile is the Dockerfile for creating a LodView image starting from the LodView sources on GitHub. This Dockerfile differs from the one included in LodView in that it does not compress the web application as a .war file, but rather deploys it in expanded form into Tomcat, so that individual files (e.g., conf.ttl) can be overridden using Docker volume mappings;
  • lodview/conf.ttl is the configuration file for LodView, customized for this example application;
  • lodview/logging.properties is the logging configuration file for Tomcat, customized so to reduce (a bit) log verbosity