A SSSOM compliant implementation of OxO that is backwards compatible with OxO version 1
docs/user/ui/oxo2-user-interface.html is a standalone
guide to the web interface — searching, reading results, how mappings are ranked, and the rough
edges. A PDF is generated from it. Open either straight from
disk; no build step, no server.
Software releases are cut by merging a pull request into stable; the push tags vX.Y.Z,
publishes a GitHub release with a Zenodo DOI, builds versioned multi-platform images and then
moves the :stable image tags. See docs/releases.md. Mapping data releases
(docs/hpc-data-release.md) and deployments are separate actions.
The backend publishes an OpenAPI 3 description of its REST API. Once the backend is running
(http://localhost:8081 in the setups below), the interactive Swagger UI is available at
http://localhost:8081/swagger-ui.html and the raw OpenAPI spec at
http://localhost:8081/v3/api-docs.
GET /api/v2/mappings/{mappingId}/support?page=0&size=20 returns all records for the selected
mapping's subject, predicate, modifier and object, including the selected record. It ignores search
filters and returns a mappings page plus group-wide justificationMethodCount and
assertedSourceCount. Pages are zero-based; size is 1–100. Asserted sources count distinct mapping
sets directly asserting that statement, not inference premises or independent evidence.
Default search order puts more distinct direct asserted source sets first: three above two, two above one, and one above zero. The existing relevance and provenance score breaks ties. Repeated records from one set and extra justification methods do not increase the source count. Explicit sorting replaces this default order. Swagger documents the full response and error contract; ADR-0054 records the design.
- Ensure docker is installed in your environment.
- Set OXO2_CONFIG environment variable - It should point to the OxO2 config file. This is how OxO2 knows which SSSOM
mappings to load. For an example config file see the
oxo-config.jsonin the root of the OxO2 code base. Copy your desired configuration file into the root directory of OXO2. E.g. if your configuration file ismy_oxo2_config.json, set OXO2_CONFIG=./my_oxo2_config.json by runningexport OXO2_CONFIG=./my_oxo2_config.json.
- To run OxO2 using docker, run
docker compose up. This will start Solr, the OxO2 backend and OxO2 frontend. The frontend will be available athttp://localhost:8080, the backend athttp://localhost:8081and Solr athttp://localhost:8983. - To stop OxO2 run
docker compose down.
All OxO2 containers now run as non-root users (oxo, UID 8389, for dataload/backend;
solr, UID 8389, for solr; node, UID 1000, for frontend). If you are upgrading
from a release where the dataload container ran as root, the existing Docker named
volumes (data, logs, solr-data) are still root-owned and the non-root dataload
container will not be able to write to them. Recreate the volumes once:
docker compose down -v
docker compose up
- Ensure you have a kubernetes cluster available. E.g. for a local k8s cluster using
minikuberunminikube start --driver=docker. - Ensure you have helm installed.
- Ensure that you have a data release such that have the complete OxO2 available at a $SOLR_HOME.
- Mount into minikube:
minikube mount --port=39000 $SOLR_HOME:/mnt/oxo/solr-data.
Note: You may need to allow port 39000 through firewall. If so, run: sudo ufw allow 39000/tcp.
- From the root directory run:
helm install oxo2 ./k8chart-local/oxo2 -n ontotools --create-namespace
- To access locally run:
kubectl port-forward deployment/oxo2-frontend 8080:8080 -n ontotools
kubectl port-forward deployment/oxo2-backend 8081:8081 -n ontotools
kubectl port-forward deployment/oxo2-solr 8983:8983 -n ontotools
and the point your browser to http://localhost:8080. The OxO2 backend will be accessible at http://localhost:8081/ and solr at http://localhost:8983.
- Run:
helm uninstall oxo2 -n ontotools.
Ensure the following software is installed and available on the user path.
- Java 25
- Maven 3.x
- Git
- Solr 9.x - This is the datastore for OxO2. Ensure SOLR_SCRIPT is set to /bin dir SOLR_HOME is set to /server/solr dir of your Solr installation.
- Nemo - Nemo is the rules engine used in OxO2. Download the latest version from Nemo latest or build from source
following instructions here. To check your Nemo installation, run
nmo --help. Ensure thatnmois available on the path. - Optionally you could use Nextflow for parallelising the OxO2 dataload. Nextflow can be installed using
curl -s https://get.nextflow.io | bash. Make sure to add it to your path.
Define the following environment variables:
- OXO2_DATA - This is where SSSOM files will be downloaded to and where any output of the OxO2 dataload will be written.
- OXO2_CONFIG - Points to the OxO2 config file. This is how OxO2 knows which SSSOM mappings to load. For an example config
file see the
oxo-config.jsonin the root of the OxO2 source code directory. NOTE: This must be the absolute path to the file. - SOLR_SCRIPT - This should point to the
bindirectory of your Solr installation. - SOLR_HOME - This should point to the root of your Solr data directory.
- SOLR_HEAP - The Solr JVM heap. Use at least
4gfor the full OxO2 index; Solr ignoresJAVA_OPTSand otherwise defaults to512m. - OXO2_SOLR_HOST - This is the URL to your Solr installation.
- NEXTFLOW_DIR - If you want to parallelise the OxO2 dataload using Nextflow, you need to specify where it can write interm results.
Here is an example script for setting environment variables:
export SOLR_SCRIPT=/home/myhome/solr-10.0.0/bin
export SOLR_HOME=/home/myhome/oxo2-data/solr
export SOLR_HEAP=4g
export PATH=$PATH:/home/myhome/nemo
export OXO2_DATA=/home/myhome/oxo2-data/dataload
export OXO2_CONFIG=/home/myhome/oxo2/my_oxo2_config.json
export OXO2_SOLR_HOST=http://localhost:8983/solr
export NEXTFLOW_DIR=/home/myhome/nextflow
- Checkout OxO2:
git clone git@github.com:EBISPOT/oxo2.gitand change to OxO2 source directory. - To build, run:
mvn clean install - Change to dataload directory:
cd ./oxo2-dataload - Run OxO2 dataload:
./loadData.nextflow(Nextflow is required). It lays down the Solr config itself and stops Solr again when it finishes. - Return to OxO2 root dir:
cd .. - Start Solr:
./startSolr.sh— always use this rather than callingsolr startdirectly, since Solr 10 defaults to SolrCloud mode, in which OxO2's cores cannot load. - Run OxO backend:
./startBackend.sh - To build and run frontend:
- Change directory to frontend:
cd oxo2-frontend - Build frontend:
npm install - Start frontend:
npm run dev - Access frontend from browser at:
http://localhost:8080/ - Backend is accessible at:
http://localhost:8081.
- Change directory to frontend:
To stop the local Solr, run ./stopSolr.sh from the OxO2 root with the same environment used
to start it. It stops only the configured port (SOLR_PORT, then the port in SOLR_URL,
defaulting to 8983) and leaves the index data in place. In a worktree, load its .envrc
with direnv or source oxo2-env.sh first so the correct instance is selected.