OLS4 (Ontology Lookup Service)

Expert guidance for the EMBL-EBI Ontology Lookup Service (OLS4), a sophisticated bioinformatics platform for browsing and searching biological ontologies.

Overview

OLS4 is a full-stack application consisting of:

Instructions

When working with OLS4, follow these steps:

1. Initial Setup and Build

**CRITICAL**: Always build in this order to avoid dependency issues:

```bash

Install Java 17 and Maven 3.x (required)

Install Node.js 20+ and npm

Build all Maven projects FIRST (takes 1-2 minutes)

mvn clean package

NEVER CANCEL this command. Set timeout to 180+ seconds.

Then build frontend

cd frontend && npm install # takes 30 seconds, timeout 120+ seconds

cd frontend && REACT_APP_ENV=dev npm run build # takes 2-3 seconds

```

2. Validate Changes with Local Testing

**ALWAYS** run local dataload tests after making changes:

```bash

Create test output directory and run minimal test case

mkdir -p /tmp/test_output

dataload/create_datafiles.sh ./testcases/owl2-primer/minimal.json /tmp/test_output --loadLocalFiles --noDates

Takes 2-3 seconds and validates core functionality

```

**DO NOT** run `test_dataload.sh` or `test_api.sh` in sandboxed environments -- they require internet access.

3. Running Components Locally

#### Option A: Full Docker Setup (requires network)

```bash

export OLS4_CONFIG=./dataload/configs/efo.json

docker compose up

DATALOAD TAKES 10-45 MINUTES. NEVER CANCEL. Timeout 3600+ seconds.

Frontend: http://localhost:8081

Backend API: http://localhost:8080

```

#### Option B: Local Development (requires external Neo4j and Solr)

```bash

Set environment variables

export NEO4J_HOME=/path/to/neo4j

export SOLR_HOME=/path/to/solr

export OLS4_HOME=/home/runner/work/ols4/ols4

export OLS_SOLR_HOST=http://localhost:8983

export OLS_NEO4J_HOST=bolt://localhost:7687

Start external services manually, then:

./dev-testing/start-backend.sh

./dev-testing/start-frontend.sh

```

4. Testing and Validation Workflow

For any code changes, complete these validation steps:

**Dataload workflow test**:

```bash

mkdir -p /tmp/validation

dataload/create_datafiles.sh ./testcases/owl2-primer/minimal.json /tmp/validation --loadLocalFiles --noDates

Verify output files (CSV/JSON) are created successfully

```

**Frontend validation**:

```bash

cd frontend

npm run build # Check for build errors

npx tsc --noEmit # Check TypeScript errors (note: codebase has 80+ existing errors)

```

**Backend validation** (requires running Neo4j/Solr):

```bash

Start backend and test basic endpoints

curl http://localhost:8080/api/ontologies

```

5. Common Development Patterns

**Repository structure**:

**Key configuration files**:

**Technology stack**:

6. Debugging and Troubleshooting

**Network restrictions**: Always use `--loadLocalFiles --noDates` flags for local testing

**Memory issues**: Adjust heap size for large ontologies:

```bash

export JAVA_OPTS="-Xms5G -Xmx10G"

```

**TypeScript errors**: Focus only on new errors introduced by your changes (codebase has 80+ existing issues)

**Build failures**:

**Version mismatches**: CI uses Java 14, local development uses Java 17 (both work)

7. CI/CD Information

Constraints

Example Usage

**Complete validation workflow after making changes**:

```bash

1. Build everything

mvn clean package # 1-2 minutes

cd frontend && npm install && npm run build # 30 seconds

2. Test dataload

mkdir -p /tmp/test && dataload/create_datafiles.sh ./testcases/owl2-primer/minimal.json /tmp/test --loadLocalFiles --noDates

3. Check frontend types

cd frontend && npx tsc --noEmit

4. If all passes, changes are validated

```

**Quick local test**:

```bash

mkdir -p /tmp/out && dataload/create_datafiles.sh ./testcases/owl2-primer/minimal.json /tmp/out --loadLocalFiles --noDates

```