OpenELIS Global 2

OpenELIS Global is open enterprise-level laboratory information system software tailored for public health laboratories. OpenELIS is used at a national scale in a variety of settings, from small general hospital labs, all the way up to national reference labs, and all sizes in between.

Thousands of users use OpenELIS daily to make their laboratory jobs easier by automating work plans, importing results from clinical analyzers, and supporting complex workflows like pathology and cytology, reducing turnaround times, and increasing result accuracy for better patient care.

OpenELIS Global meets all relevant ISO and SLIPTA requirements for the accreditation of labs.

OpenELIS adheres to the strictest of security standards to keep your data safe and supports fully featured, standards-based interoperability to make it easy to receive lab orders and send results to other systems

Please vist our website for more information.

You can find more information on how to set up OpenELIS at our docs page

CI Status

CI Architecture

For the current fork/non-fork E2E validation design, artifact contracts, and checkpoint/status model, see specs/plans/ci-e2e-architecture-spec.md.

For operational troubleshooting of the E2E wrapper and downstream execution, see specs/plans/e2e-ci-operator-model.md.

Contributing

We welcome community contributions to help improve OpenELIS Global!

1. Read our Dev Environment Setup Instructions on the project wiki.
2. Check out our CONTRIBUTING guide for detailed contribution practices and pull request tips.

Requirements

1. You need to install Docker and Docker compose

2. For development , you need to install Java 21

For Offline Installation Using the OpenELIS Global2 Installer

Download the OpenELIS Global Installer for each Release from the Release Assets

see full installation instructions for Offline Installation

For running OpenELIS Global2 in Docker with default Settings out of the Box

see OpenELIS-Docker setup

For Running OpenELIS Global2 from Source Code

Prerequisites for all methods below:

Before running any docker compose command, you must create a .env file with your environment configuration:

cp .env.example .env

Then edit .env to customize settings for your environment (database passwords, domain, etc.). See .env.example for detailed documentation of each variable.

IMPORTANT: Never commit .env to version control as it contains secrets and server-specific settings. CI copies .env.example to .env before running docker compose.

Running OpenELIS Global2 using docker compose With published docker images on dockerhub

docker compose up -d

Running OpenELIS Global2 using docker compose with docker images built directly from the source code

docker compose -f build.docker-compose.yml up -d --build

Running OpenELIS Global2 with docker compose For Development

Here Artifacts (ie the War file and React code) are compiled/built on the local machine outside docker and just mounted into the docker compose setup. This speeds up the development process

1. Fork the OpenELIS-Global Repository and clone the forked repo. The username below is the username of your Github profile.

    git clone https://github.com/username/OpenELIS-Global-2.git
   

2. innitialize and build sub modules

   cd OpenELIS-Global-2
   git submodule update --init --recursive
   cd dataexport
   mvn clean install -DskipTests
   

3. Navigate back to the repository directory:

    cd ..
   

4. Build the War file

     mvn clean install -DskipTests -Dmaven.test.skip=true
   

5. Start the containers to mount the locally compiled artifacts

   docker compose -f dev.docker-compose.yml up -d
   

   Note : For Reflecting Local changes in the Running Containers ;

6. Any Changes to the Front-end React Source Code will be directly Hot Reloaded in the UI

7. For changes to the Back-end Java Source code

8. Run the maven build again to re-build the War file

    mvn clean install -DskipTests -Dmaven.test.skip=true
   

9. Recreate the Openelis webapp container

   docker compose -f dev.docker-compose.yml up -d  --no-deps --force-recreate oe.openelis.org
   

The Instances can be accessed at

Note: If your browser indicates that the website is not secure after accessing any of these links, simply follow these steps:

1. Scroll down on the warning page.
2. Click on the "Advanced" button.
3. Finally, click on "Proceed to https://localhost" to access the development environment.

Formating the Source code after making changes

1. After making UI changes to the frontend directory , run the formatter to properly format the Frontend code

   cd frontend
   npm run format
   

2. After making changes to the backend directory, run the formatter to properly format the Java code

   mvn spotless:apply
   

To ensure your code passes the same checks as the CI pipeline

Recommended: Use the CI check scripts (replicates exact CI workflow):

# Run backend CI checks (formatting + build + tests)
./scripts/run-ci-checks.sh

# Run frontend CI checks (formatting + unit tests + E2E tests)
./scripts/run-frontend-ci-checks.sh

# Run both (full CI simulation)
./scripts/run-ci-checks.sh && ./scripts/run-frontend-ci-checks.sh

Options:

• --skip-submodules: Skip submodule build (faster, for quick checks)
• --skip-tests: Skip tests (formatting only)
• --skip-e2e: Skip E2E tests (frontend only)

Manual commands (if you prefer to run steps individually):

1. Run Code Formatting Check (Backend). This command checks code formatting and performs validation similar to the CI

   mvn spotless:check
   

2. Run Build Check (Backend). This command builds the project similar to CI

   mvn clean install -Dspotless.check.skip=true
   

3. To run Individual Integration Test

    mvn verify -Dit.test=<packageName>.<TestClassName>
   

   DBUnit test data note: DB-backed integration tests typically load DBUnit Flat XML datasets from src/test/resources/testdata/ via executeDataSetWithStateManagement("testdata/<file>.xml"). Prefer datasets over inline SQL setup/cleanup to avoid test data pollution.

4. Run Frontend Formatting, Build, and E2E Test Checks similar to CI

   Note: Frontend checks will only pass successfully if your development environment is properly set up and running without issues.

   cd frontend/ # from project directory
   npm install
   npm run build
   npm run cy:run # this will run e2e testing same CI
   

AI-Assisted Development (SpecKit)

This project uses GitHub SpecKit for Spec-Driven Development (SDD). AI coding agents can use slash commands to create specifications, plans, and tasks.

Available Commands:

• /speckit.specify - Create feature specification
• /speckit.plan - Generate implementation plan
• /speckit.tasks - Generate task breakdown
• /speckit.implement - Execute implementation
• /speckit.analyze - Validate consistency

Reference Documentation:

• AGENTS.md - Comprehensive guide for AI coding agents
• Constitution: .specify/memory/constitution.md - Governance principles
• Feature Example: specs/001-sample-storage/ - Complete SDD example

Testing Resources

For comprehensive testing guidance, see:

• Testing Roadmap: .specify/guides/testing-roadmap.md - Complete testing guide for both agents and humans
• Test Templates: .specify/templates/testing/ - Standardized test templates
• AGENTS.md: Testing Strategy section - Overview of testing approach
• Test Data Strategy: .specify/guides/test-data-strategy.md - Unified test data management guide

Test Data Setup

For E2E testing, integration testing, and manual testing, load test fixtures:

# Basic usage (loads and verifies automatically)
./src/test/resources/load-test-fixtures.sh --profile=core

# Harness fixture lane (includes HARN-* lane data)
./src/test/resources/load-test-fixtures.sh --profile=harness

# Reset database before loading (clean state)
./src/test/resources/load-test-fixtures.sh --profile=core --reset

# Load without verification (faster)
./src/test/resources/load-test-fixtures.sh --profile=core --no-verify

Note: The unified loader script provides dependency checks, verification, and reset capabilities. See Test Data Strategy Guide for details.

Pull request guidelines

Please follow the pull request tips in order to make life easy for the code reviewers by having a well defined and clean pull request.

code of conduct

Please see our Contributor Code of Conduct