EBISPOT / ols4

The Ontology Lookup Service (OLS) is a repository for biomedical ontologies that aims to provide a single point of access to the latest ontology versions. It provides a website, REST API, and MCP server. See also: • The public OLS instance at EMBL-EBI: https://www.ebi.ac.uk/ols4/ • OLS4: a new Ontology Lookup Service for a growing interdisciplinary knowledge ecosystem • REST API docs • MCP endpoint (Streamable HTTP): If you use OLS in your work, please cite our recent publication in Bioinformatics . --- This repository contains three projects: • The dataloader ( directory) • The API server ( directory) • The React frontend ( directory) Deploying OLS4 First run the OLS dataload (requires Docker): OLS4_CONFIG=./dataload/configs/efo.json ./dataload.sh This will create Solr and Neo4j databases in the directory. Now start the OLS stack: HOST_UID=$(id -u) HOST_GID=$(id -g) docker compose up You should now be able to access the OLS4 frontend at . If you want to test it with your own ontology, copy the OWL or RDFS ontology file into this repository folder. Then make a new config file for your ontology; you can use from as a template. For the property in the config, use the relative path in this repository to your ontology e.g. . Then follow the above steps for efo with the config filename you created. Deployment: Using Kubernetes with GitHub Packages To deploy OLS4 using Kubernetes, Docker images built and uploaded to this repository (using GitHub Packages) are utilized. Software requirements are as follows: • Kubernetes command-line tool, _kubectl_ • Kubernetes package manager, _helm_ Create data archives for Solr and Neo4j First run the OLS dataload (requires Docker): OLS4_CONFIG=./dataload/configs/efo.json ./dataload.sh This will create Solr and Neo4j databases in the directory. Startup OLS4 deployment Uninstall existing deployments, if any, before installing a new one. Do not forget to set environment variable. **IMPORTANT**: The use of is to specify the Docker image (uploaded to this repository) that will be used in the deployment. If not familiar, simply use either the or image. export KUBECONFIG= helm install ols4 /k8chart/ols4 --set imageTag=dev Developing OLS4 OLS is different to most webapps in that its API provides both full text search and recursive graph queries, neither of which are possible and/or performant using traditional RDBMS. It therefore uses two specialized database servers: **Solr**, a Lucene server similar to ElasticSearch; and **Neo4j**, a graph database which is also used to store embedding vectors. • The directory contains the code which turns ontologies from RDF (specified using OWL and/or RDFS) into JSON and CSV datasets which can be loaded into Solr and Neo4j, respectively; and some minimal bash scripts which help with loading them. • The directory contains a Spring Boot application which hosts the OLS API over the above Solr and Neo4j instances • The directory contains the React frontend built upon the above. Running OLS4 components using Docker You can run OLS4, or any combination of its consistuent parts (dataload, backend, frontend) in Docker. When developing, it is often useful to run, for example, just Solr and Neo4j in Docker, while running the API server locally; or to run Solr, Neo4j, and the backend API server in Docker while running the frontend locally. First install the latest version of Docker Desktop (or compatible, such as Rancher Desktop) if you are on Mac or Windows. This now includes the command. If you are on Linux, make sure you have the plugin installed ( on Ubuntu). Then, start up the components you would like to run. For example, Solr and Neo4j only (to develop the backend API server and/or frontend): docker compose up --force-recreate --build --always-recreate-deps --attach-dependencies ols4-solr ols4-neo4j This will start up Solr and Neo4j with your new dataset on ports 8983 and 7474, respectively. To start Solr and Neo4j **AND** the backend API server (to develop the frontend): docker compose up --force-recreate --build --always-recreate-deps --attach-dependencies ols4-solr ols4-neo4j ols4-backend To start everything, including the frontend: docker compose up --force-recreate --build --always-recreate-deps --attach-dependencies ols4-solr ols4-neo4j ols4-backend ols4-frontend Making the tests pass OLS has a comprehensive suite of automated CI tests for the dataload and API. If code changes change the output such that it no longer matches (mock dataload) and/or (full Nextflow dataload and API) the CI will fail, and you will need to update the expected output. Before running your testcases, ensure that your work is already committed. Create a new branch based on the branch you worked on but with a suffix. I.e., if your branch is called "fix-xyz", the new branch for the testcases will be . We commit testcases to a separate branch due to the large number of files updated when testcases are run. Testing the mock dataload First, build an up to date Docker image for the dataload: docker build -t ols4-dataload:local -f ./dataload/Dockerfile . --no-cache Remove the old contents from your local working tree: rm -rf testcases_expected_output/* Re-populate directory with updated test output: docker run \ -v $(pwd)/testcases_expected_output:/opt/ols/testcases_output \ ols4-dataload:local \ bash -c "cd /opt/ols && ./test_dataload.sh" Now you can inspect any changes to the files in and make sure they are intentional, e.g. using or from VS Code. When you are happy, stage and commit the updated . git add -A testcases_expected_output git commit -m "Update testcase output" Testing the full Nextflow dataload and API First follow the instructions above for testing the mock dataload. Then build up to date Docker images for remainder of the OLS stack: For backend use following docker command: docker build -t ols4-backend:local -f ./backend/Dockerfile . --no-cache For frontend use following do…