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

All badges report the status of the latest merge to develop (event=push), not per-PR runs.

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.
3. To report a security vulnerability, follow SECURITY.md (private reporting — not public issues).

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

Supported versions, branches, and the versioning policy are described in RELEASES.md.

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

Development has one supported startup path. From the root of any clone or Git worktree, run:

scripts/dev-stack up

The command initializes the required submodules, uses Java 21, builds the local WAR and analyzer components, and starts the complete OpenELIS + analyzer harness. Its Compose project, containers, images, networks, ports, and volumes are derived from the worktree path, so multiple worktrees can run concurrently. The harness analyzer scenarios are created idempotently through authenticated application services after login readiness; startup never seeds the database directly. Use --no-scenarios only when testing an intentionally empty system.

Useful commands:

scripts/dev-stack status
scripts/dev-stack url
scripts/dev-stack playwright playwright/tests/foundational/core/example.spec.ts
scripts/dev-stack playwright --project=setup  # verify authentication only
scripts/dev-stack logs -f oe.openelis.org
scripts/dev-stack down
scripts/dev-stack down --volumes --yes  # explicit data reset

The playwright command discovers this worktree's URL, loads credentials from the existing environment or .env, and runs the shared authentication setup automatically. To exercise a deployed environment with the identical path, set only its URL:

BASE_URL=https://amr.openelis-global.org \
  scripts/dev-stack playwright playwright/tests/foundational/core/microbiology-whonet-export.spec.ts

Local development needs no configuration: .env is created from .env.example, the proxy binds random loopback ports, and scripts/dev-stack url prints the browser URL. Frontend source remains hot-reloaded. Re-run scripts/dev-stack up after backend or analyzer component changes.

The published development frontend dependency image is reused when package.json, package-lock.json, and frontend/Dockerfile match develop; worktree source is still mounted for hot reload. If any of those inputs differ, the command automatically builds an isolated frontend image. Set DEV_STACK_BUILD_FRONTEND=true only to force that rebuild.

For a domain-enabled development server, set a real LETSENCRYPT_DOMAIN and LETSENCRYPT_EMAIL in .env, then run the same scripts/dev-stack up command. It binds ports 80/443, renders the named nginx hosts, and uses the existing Let's Encrypt HTTP-01 flow. DNS for both the primary domain and bridge.<domain> must resolve to the server. Port and bind overrides are listed in .env.example for hosts that already have an external router; those hosts should terminate TLS at that router and set DEV_STACK_TLS=self-signed for the private upstream.

Do not invoke the development Compose layers directly. CI, release, and packaged installation commands remain separate operational interfaces.

The Instances can be accessed at

Instance	URL	credentials (user : password)
Legacy UI	<scripts/dev-stack url>/api/OpenELIS-Global/	admin: adminADMIN!
New React UI	output of scripts/dev-stack url	admin: adminADMIN!

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

Run the full local PR test package from one committed revision:

./scripts/run-ci-checks.sh

The runner uses detached checkouts at the current commit and runs backend, frontend, the shared build, core Playwright, analyzer Playwright, and all three Cypress shards. Each E2E suite gets a fresh isolated database. It reports every lane and exits unsuccessfully if any required lane fails or does not run. Logs and the source commit are saved in the printed artifact directory. Run ./scripts/run-ci-checks.sh --plan to see the lanes without starting them, or use --artifact-dir PATH to choose where evidence is saved. The targeted E2E scripts remain available for debugging a single lane; their passing result alone is not full CI parity. GitHub-only publication, security upload, and checkpoint jobs still need their GitHub checks.

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
   

Environmental & Compliance-Scoped Result Evaluation

Environmental orders support multi-standard compliance evaluation. When an order is placed with one or more compliance standards selected (e.g. PP No. 22/2021, WHO-DWG-4), the result entry screen shows per-standard PASS/FAIL pills inline with each test result under a Status — Per Regulation column.

How it works:

1. Admin configures compliance standards and their per-test thresholds under Administration → Compliance Standards. Each standard has parameter groups with thresholds (RANGE, MINIMUM, MAXIMUM, etc.) linked to specific tests.

2. When placing an environmental order, select the applicable compliance standards in the Applicable Compliance Standards section. These are stored in the sample_compliance_standards join table.

3. On result entry, the system evaluates each entered value against the compliance_threshold rows for that test + standard combination and returns complianceStatuses (array of {standardId, standardName, pass}) alongside each result row.

4. The result entry screen renders green PASS — <standard> or red FAIL — <standard> pills. The column is hidden when no compliance standards are attached to the loaded result set.

Key entities:

• compliance_standard — the regulatory standard (e.g. PP No. 22/2021)
• parameter_group — groups thresholds within a standard
• compliance_threshold — per-test threshold with type and bounds
• sample_compliance_standards — join table linking a sample to its standards

Non-environmental and non-compliance orders are unaffected; the existing normal/abnormal background-colour logic is unchanged.

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 profile: core fixtures; analyzer orders are created through the API
./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