ORKG Backend API

This repository contains a backend API for the ORKG based on the Spring Framework. It is written in Kotlin as a proof-of-concept and for experimenting with a possible architecture and technologies.

Building and running

Prerequisites

The backend API can be run stand-alone. However, it needs other services to start properly. Services are managed via Docker (CE) and the Docker Compose plugin. Please follow the respective installation instructions for your operating system or distribution.

Warning

The Docker Compose standalone binary will not work, you need the Docker Compose plugin for the Docker CLI. Users of Docker Desktop will have it installed already, and do not need any additional installation.

Stand-alone application

Note	Running the application stand-alone is mostly for development purposes. It still needs Neo4j and PostgreSQL configured and running. If you want to test the application, please refer to the section Building a Docker image below.

To build and run the API, type:

./gradlew bootRun

This will start a server running on http://localhost:8080.

The REST entry-point is http://localhost:8080/api/.

Building a Docker image

Note	The following commands assume that you added your user to the docker group as suggested in the documentation. If you did not do so, you have to prefix all commands with sudo.

The Docker image can be build with Jib. Run:

./gradlew jibDockerBuild

The application can be run via Docker Compose. After installing it, run:

docker compose up -d

Warning

In the past, it was possible to use this software with the standalone Docker Compose binary, which is deprecated by Docker Inc. for quite a while now. We only support using the Docker Compose plug-in now, which is installed by default in most Docker installations.

This will start the application image and all dependent containers. It will take care of linking all containers so the services can see each other. You can start and connect all services yourself but this is not recommended.

The application can be accessed via http://localhost:8080/. The other services can be accessed via the URLs described in the table "Images and their default end-points".

To diagnose problems, check the logs with:

docker compose logs -f

To restart from scratch, run:

docker compose down

Data is saved to named volumes for Neo4j and Postgres, respectively, and persists even if you destroy the containers. If you also need to get rid of the data use the docker volume sub-commands to locate and remove them.

Docker images

Note	This section is only relevant if you want to work with some of the components in isolation. Please refer to the section Building a Docker image if you want to run the application via Docker.

Caution

The recommended way to start the Backend is (still) via Docker Compose.

Image end-points

The images will provide the following end-points:

Table 1. Images and their default end-points

Image	Container name	End-points
registry.gitlab.com/tibhannover/orkg/orkg-backend	orkg-backend_api_1	http://localhost:8080/api/ (REST API)
neo4j	orkg-backend_neo4j_1	http://localhost:7474/browser/ (HTTP) localhost:7687 (BOLT)
postgres:11	orkg-backend_postgres_1	localhost:5432

All exposed ports are bound to localhost (IPv4 and IPv6) to not "leak" to all networks. If you need to expose those to your host network, refer to the Docker documentation and change the Compose file accordingly.

Notes on the Neo4j Docker image

The Neo4j Docker image includes the following extensions:

• Awesome Procedures On Cypher (APOC)

APOC is required by the ORKG. You need to include it when you setup Neo4j in your environment manually.

REST API documentation

The documentation can be found at https://tibhannover.gitlab.io/orkg/orkg-backend/api-doc/index.html.