🧪 OpenLIMS

Open-source, self-hosted Laboratory Information Management System for practical lab workflows.

Features · Architecture · Local Development

---

Overview

v0.38.0 — Lab configuration from Settings

Settings now brings together the existing field, workflow/template, role and sharing editors. Administrators can restrict supported manual sample-status transitions with required audit reasons, revision conflict protection, validation against QC bypasses/dead ends, and a saved-defaults restore flow. Read-only users can inspect the policy. Run backend migrations before upgrading. See the English/Spanish configuration guide.

v0.37.1 — Invitation browser regression fix

Update the invitation browser test for the new password-success guidance. Verify the Getting started instructions, sign-in link, removed password form, and cleared invitation token after successful setup.

v0.37.0 — Guided lab onboarding

Getting started guides users through their lab’s real workflow templates, preserves their first experiment across sessions, and shows actual step progress. Account notifications and persistent invitation/password setup status help administrators bring users onboard. Includes English/Spanish guidance and permission, retry, and workflow regressions. Run backend migrations before upgrading the frontend. See the onboarding guide.

OpenLIMS is an open-source, self-hosted Laboratory Information Management System built to support practical lab workflows such as sample tracking, project organization, collaborative experiment notebooks, inventory custody, internal workflow requests, instrument data ingestion, sequence analysis, local BLAST search, mass spectrometry review, legacy data migration, audit trails, reporting, role-based access control, and an assistant with optional OpenAI or local Ollama support that remains read-only unless a user explicitly confirms a supported action.

The project is designed as a lightweight, configurable, production-style foundation for research labs, small biotech teams, core facilities, and developer teams that need more structure than spreadsheets but do not want the cost or complexity of a traditional enterprise LIMS.

Status: OpenLIMS is currently a production-style prototype. It is not yet a fully validated clinical, diagnostic, or regulated production LIMS.

Current development version: v0.38.0 — Lab configuration from Settings.

Deployment Access

Hosted deployment addresses and access credentials are intentionally not published in the repository. Authorized users should obtain access details directly from the repository owner.

---

✨ Features

---

🧭 Table of Contents

• Core Concepts
• OpenLIMS Assistant
• Architecture
• Permissions
• Local Development
• Optional Local Ollama Assistant
• Testing
• Deployment Notes
• Current Project Status
• Roadmap

---

🧬 Core Concepts

Samples

Samples are the central records in OpenLIMS. A sample can be assigned to a project, placed in a container, linked to results, connected to sequence records, used in BLAST or alignment workflows, associated with mass spectrometry runs, and connected to external IDs from legacy systems.

Supported sample statuses:

OpenLIMS supports controlled status changes with a required reason for change, helping create a stronger chain-of-custody and audit trail.

Projects

Projects act as shared workspaces for lab teams. They can contain samples, sequence workspaces, imports, BLAST jobs, alignments, mass spectrometry runs, notes, migration jobs, and project activity.

Project membership controls what non-admin users can see and modify.

Cross-Project Sample Linking

A sample has one primary project, but it can also be linked to additional projects. This supports cases where a sample belongs to one study or team but needs to be visible to another project without transferring ownership.

Sample: S-ALPHA-001
Primary Project: PRJ-ALPHA
Linked Projects: PRJ-BETA, PRJ-GAMMA

Linked projects provide visibility, while primary project ownership controls modification and import permissions.

Sample Lineage and Chain of Custody

OpenLIMS records directed relationships between source and derived samples for aliquots, splits, derived materials, and pooled components. Lineage links reject self-links and cycles, retain the amount and unit when supplied, and require an audited reason. A derived sample can be created directly from the Traceability workspace while inheriting the source project, linked-project visibility, batch, and applicable default workflow.

Barcode or sample-ID scans can record receipt, check-out, check-in, transfer, storage movement, processing, and disposal. Each custody event preserves the previous and new container and custodian, the operator, scan value, timestamp, and handling reason. Disposal clears physical custody and archives the sample.

Inventory

OpenLIMS models storage from a physical site down to an individual well:

Site → Building → Laboratory → Room → Freezer → Shelf → Rack → Box → Well

Locations, containers, samples, reagent lots, and registered materials can have generic barcode identities. Scanned operations create immutable transactions for receive, move, transfer, count, consume, adjust, quarantine, disposal, and return. Every quantity transaction records the actor, reason, unit, before and after values, and linked experiment, request, or work item when supplied.

Inventory items and lots retain vendor, catalog, manufacturer, received/opened and expiration dates, cost, storage conditions, chemical identity, hazards, GHS classifications, SDS/COA files, and disposal guidance. Plate maps support well-level placement, while reservations, expiration/reorder alerts, cycle counts, and reconciliation keep available stock auditable.

---

📥 Instrument Imports

OpenLIMS supports CSV-based instrument imports and direct API ingestion.

Instrument profiles define:

• Instrument code and name
• Delimiter
• Sample ID column
• Column mappings
• Value types
• Numeric limits
• Allowed values
• Header row behavior
• Auto-detection of true CSV headers

Flexible CSV Imports

Some instrument exports include metadata rows before the real CSV header. OpenLIMS can scan for the sample ID column and detect the actual header row.

Instrument,Example Analyzer
Run ID,RUN-001
Operator,Peter
sample_id,result,operator,qc_status
S-ALPHA-001,pass,Peter,PASS

---

🔁 Data Migration Toolkit

OpenLIMS includes a data migration toolkit for bringing legacy lab database exports into OpenLIMS in a safer, reviewable way.

SISBI / legacy PostgreSQL, MySQL, SQLite, or CSV
   ↓
Migration profile
   ↓
Read-only datasets and field mapping
   ↓
Preview / dry run
   ↓
Confirm import
   ↓
Projects, inactive users, samples, metadata, work items, and historical results

The migration toolkit supports:

• Migration profiles
• Reusable field mappings
• Saved mapping templates that can be applied to another compatible profile
• CSV upload
• Director-managed read-only PostgreSQL, MySQL/MariaDB, and SQLite sources
• Schema/table inspection without arbitrary SQL
• Separate datasets for projects, users, samples, and historical results
• Preview / dry-run before import
• Required-field, data-type, relationship, status, and timestamp validation
• A source-and-mapping fingerprint that blocks a changed source after preview
• Per-job conflict policies: skip, merge blank fields, overwrite mapped fields, or create unique copies
• Project creation or matching
• Inactive user creation with unusable passwords and safe non-admin roles
• Sample creation or matching
• External sample IDs and aliases
• Custom field values
• Work items and results
• Migration job history
• Paginated migration row review
• Skipped/error row filtering
• CSV export for migration review
• Reconciliation reports with source, action, status, and entity totals
• Director-controlled rollback of tracked creations and updates

Database passwords are never stored in OpenLIMS. Configure the password in an environment variable, enter only that variable's name in the connection, and use a source account that has SELECT permission only. Remote hosts must also be listed in MIGRATION_DB_ALLOWED_HOSTS. Each dataset has a row safety limit; the final commit re-reads and fingerprints the source before writing anything. Conflict policy is part of that fingerprint. Each committed job records the objects it created and the original values it changed, allowing a director to perform a guarded rollback. Rollback is blocked if later related data would be put at risk.

External Sample IDs and Aliases

OpenLIMS can preserve legacy identifiers from older databases or spreadsheets.

Sample: S-UW-001
Source System: UW Legacy DB
Label: legacy_specimen_id
External ID: SP-00921

---

🤖 OpenLIMS Assistant

OpenLIMS includes a read-only assistant for quickly finding and summarizing records inside the system.

The assistant can help users ask questions such as:

• Show what needs attention across accessible lab work
• Find a sample by sample ID
• Summarize a project
• Show failed migration jobs
• Show skipped migration rows
• Explain why a migration job failed
• Identify the current logged-in OpenLIMS user

The assistant uses safe backend tools as the source of truth. It does not directly modify database records.

The attention summary is permission-filtered and checks samples that have remained in an active status for more than three days, missing sample information, QC review states, aged open work items, failed instrument imports, failed BLAST and alignment jobs, and admin-only system health warnings. Inventory quantity, reservation, reorder, and expiry alerts are also included when they need attention.

Assistant Modes

If an LLM is unavailable, the assistant falls back to OpenLIMS Rules mode.

The rules layer also handles common conversational requests such as greetings, help, the current application date, and the current application time. If a question is unrelated to OpenLIMS but can be answered conversationally, the constrained route classifier can send it to a separate general-conversation prompt. That prompt receives no database records or tool output and cannot run an OpenLIMS action. Requests that appear to require unsupported laboratory data or application operations remain explicit unsupported requests instead of being answered as general chat.

The UI displays the active engine/model, such as:

Using: OpenLIMS Rules
Using: OpenAI · gpt-5
Using: Ollama · llama3.2:1b

---

🧫 Sequence, BLAST, and Mass Spec Workflows

Sequence Workspaces

Users can:

• Create sequence records
• Link sequences to samples and projects
• Store sequence metadata
• Add sequence features
• Import FASTA files
• Use sequences in alignment and BLAST workflows

Sample → FASTA Import → Sequence Workspace → Alignment Job → BLAST Search

Clustal Omega Alignments

OpenLIMS can queue Clustal Omega alignment jobs asynchronously. Alignment jobs store input FASTA, aligned FASTA, sequence count, alignment summary, status, and downloadable output.

Local BLAST Search

OpenLIMS includes local BLAST support using NCBI BLAST+.

Users can:

• Upload FASTA files as local BLAST databases
• Build BLAST databases
• Run blastn searches
• Run blastp searches
• View parsed BLAST hits
• Inspect identity, e-value, rank, accession, and aligned regions

Mass Spectrometry Workflows

OpenLIMS includes mass spectrometry support using pyOpenMS and OpenMS-compatible formats.

Supported workflows include:

• mzML, mzXML, and mzData upload
• featureXML parsing
• consensusXML parsing
• mzID / mzIdentML identification summaries
• TIC preview charts
• Spectra counts
• MS1/MS2 counts
• Retention time ranges
• m/z ranges
• Peak summaries
• Detected features
• Protein and peptide summaries
• Run comparison by project, sample, or manual selection

---

🧾 Audit Trail and Reports

OpenLIMS records important activity as audit events, including:

• Sample created
• Sample status changed
• Sample linked/unlinked from project
• Container assigned
• Attachment uploaded
• Results imported
• Migration imported
• FASTA imported
• Alignment queued or completed
• BLAST database built
• BLAST search completed
• Mass spec run uploaded or processed
• Settings changed

For controlled sample status changes, OpenLIMS records actor, before/after state, changed fields, reason for change, and timestamp.

Reports and CSV exports include:

• Project summaries
• Sample inventory
• QC review
• Import summaries
• Alignment summaries
• BLAST summaries
• Audit activity

---

⚡ Real-Time Job Updates

Background jobs run through Celery and Redis. OpenLIMS uses Django Channels and WebSockets to update the frontend when jobs change status.

Supported live-update workflows include:

• CSV imports
• Alignment jobs
• BLAST database builds
• BLAST searches
• Mass spec processing

---

🔐 Permissions

OpenLIMS uses role-based permissions and project-scoped access control. Browser sessions use HttpOnly JWT cookies with CSRF protection, refresh-token rotation, and logout invalidation. Bearer JWT authentication remains supported for scripts and non-browser API clients.

Sample Access Rules

Linked-project access allows a user to see a sample, but it does not automatically grant edit or import permissions.

---

🏗 Architecture

High-level architecture:

React Frontend / Production Nginx
   ↓
Django REST Framework API
   ↓
PostgreSQL

Redis
   ↓
Celery Worker
   ↓
Imports / Migrations / Alignments / BLAST / Mass Spec Jobs

Daphne + Django Channels
   ↓
WebSocket job updates

OpenLIMS Assistant
   ↓
Safe read-only backend tools
   ↓
Optional OpenAI or local Ollama summary

Main Django Apps

---

💻 Local Development

1. Clone the repository

git clone https://github.com/Mokey2002/OpenLIMS.git
cd OpenLIMS

2. Create the environment file

cp deploy/.env.example deploy/.env

Example local environment:

DJANGO_DEBUG=1
DJANGO_SECRET_KEY=dev-secret-key
DJANGO_ALLOWED_HOSTS=localhost,127.0.0.1
CSRF_TRUSTED_ORIGINS=http://localhost:5173,http://127.0.0.1:5173

POSTGRES_DB=openlims
POSTGRES_USER=openlims
POSTGRES_PASSWORD=openlims
DB_HOST=db
DB_PORT=5432

CELERY_BROKER_URL=redis://redis:6379/0
CELERY_RESULT_BACKEND=redis://redis:6379/1
CHANNEL_REDIS_URL=redis://redis:6379/2

INSTRUMENT_API_KEY=my-shared-lab-instrument-key

OPENLIMS_ASSISTANT_LLM_ENABLED=false
OPENLIMS_ASSISTANT_LLM_PROVIDER=ollama
OPENLIMS_ASSISTANT_LLM_ROUTING_ENABLED=true
OPENLIMS_ASSISTANT_LLM_ROUTING_MIN_CONFIDENCE=0.65
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=llama3.2:1b
OLLAMA_TIMEOUT_SECONDS=25

3. Start services

docker compose -p openlims -f deploy/docker-compose.yml up -d --build

4. Run migrations

docker compose -p openlims -f deploy/docker-compose.yml exec api python manage.py migrate

5. Seed demo data

docker compose -p openlims -f deploy/docker-compose.yml exec api python manage.py seed_demo

The command is idempotent and seeds connected demonstrations for projects, samples, batches, custom metadata, lineage, barcode custody, inventory, reservations, scan transactions, plate maps, cycle counts, workflow requests, notebooks and signed experiments, workflows, results, QC, instrument imports, migration previews and rollback, Registry records, Molecular Biology revisions and assembly plans, BLAST, alignments, mass spectrometry, reports, notifications, audit history, shared links and attachments, and assistant confirmations. The seeder does not create, require, display, or change passwords. Existing account credentials are preserved, while newly created demo identities are non-login accounts used for realistic ownership, assignment, QC, and audit history. Sign in with an existing OpenLIMS administrator account to explore the seeded data.

The Registry and Notebook feature flags are enabled for the comprehensive demo. Studies and Insight remain disabled because those modules are still under development.

6. Open the app

---

🦙 Optional Local Ollama Assistant

OpenLIMS can run the assistant with a local Ollama model instead of an external LLM provider.

Enable the assistant in deploy/.env:

OPENLIMS_ASSISTANT_LLM_ENABLED=true
OPENLIMS_ASSISTANT_LLM_PROVIDER=ollama
OPENLIMS_ASSISTANT_LLM_ROUTING_ENABLED=true
OPENLIMS_ASSISTANT_LLM_ROUTING_MIN_CONFIDENCE=0.65
OLLAMA_BASE_URL=http://ollama:11434
OLLAMA_MODEL=llama3.2:1b
OLLAMA_TIMEOUT_SECONDS=25

OpenLIMS first uses normalized deterministic routes. If no route matches, the configured model may return a constrained, confidence-gated route hint from a fixed allowlist. OpenLIMS then runs the normal permission checks, frozen previews, and confirmation requirements. Invalid, low-confidence, or unavailable model classifications fall back to an honest rule-based response.

Start the Ollama container:

docker compose -p openlims -f deploy/docker-compose.yml up -d ollama

Pull a small model:

docker compose -p openlims -f deploy/docker-compose.yml exec ollama ollama pull llama3.2:1b

Restart the API and frontend:

docker compose -p openlims -f deploy/docker-compose.yml restart api frontend

The Assistant page will show which engine is active: OpenLIMS Rules, OpenAI, or Ollama.

---

🧪 Testing

Run backend tests:

docker compose -p openlims -f deploy/docker-compose.yml exec api pytest -v

Run Django checks:

docker compose -p openlims -f deploy/docker-compose.yml exec api python manage.py check

Run frontend build:

cd frontend
npm ci
npm run build

Run Playwright browser tests after starting a testable OpenLIMS environment:

cd frontend/e2e
npm ci
npx playwright install chromium
npm test

The CI workflow also validates makemigrations --check, production Compose configuration, the production frontend build, secure-cookie authentication, CSRF behavior, /api/v1/ browser traffic, workflow navigation, logout/session invalidation, and the v0.29 performance/pagination regressions.

---

🩺 Health Check

OpenLIMS includes a health endpoint:

curl http://localhost:8000/api/health/

The health check verifies:

• Database
• Redis/cache
• Clustal Omega
• blastn
• blastp
• makeblastdb
• pyOpenMS

---

🔖 Frontend Version Footer

The frontend footer should use the generated frontend/src/version.js file instead of a hardcoded version string.

Recommended footer source:

OpenLIMS {OPENLIMS_VERSION}

The version file can be generated from the latest Git tag during frontend dev/build so the footer stays aligned with releases.

---

🚀 Deployment Notes

OpenLIMS can run locally, on a private lab server, on a VM, or on cloud infrastructure.

deploy/docker-compose.prod.yml provides the production-style stack introduced in v0.28.1. v0.29.0 improves runtime efficiency on that stack with reusable PostgreSQL connections, optional Redis-backed Django caching, gzip compression, immutable hashed-asset caching, route-level frontend code splitting, and larger bounded API pages. The production stack runs Django under Daphne, serves the built React frontend through Nginx, keeps PostgreSQL and Redis internal by default, persists database/cache/media/static data, includes health checks, and exposes the web service on ${OPENLIMS_HTTP_PORT:-8080}. Ollama remains optional through the llm Compose profile.

Start from the production environment template:

cp deploy/.env.prod.example deploy/.env

Replace placeholder secrets, configure DJANGO_ALLOWED_HOSTS and CSRF_TRUSTED_ORIGINS for the public hostname, and then start the stack:

docker compose -p openlims -f deploy/docker-compose.prod.yml up -d --build

A typical production-style deployment uses:

Trusted TLS reverse proxy / load balancer (optional when TLS is terminated upstream)
   ↓
Nginx React frontend
   ↓
Django API / Daphne ASGI
   ↓
PostgreSQL

Redis
   ↓
Celery Worker

For real-time updates, the production web tier forwards WebSocket traffic under /ws/* to the Django/Daphne API service.

Performance settings

The production environment template enables the recommended connection/cache settings:

DB_CONN_MAX_AGE=60
CACHE_URL=redis://redis:6379/3

DB_CONN_MAX_AGE reuses healthy PostgreSQL connections instead of reconnecting for each request. Redis database 3 is reserved for Django application caching; Celery broker/results and Channels continue to use Redis databases 0, 1, and 2 respectively.

Database Backup

Create a backup:

docker compose -p openlims -f deploy/docker-compose.prod.yml exec db pg_dump -U openlims openlims > openlims_backup.sql

Restore a backup:

cat openlims_backup.sql | docker compose -p openlims -f deploy/docker-compose.prod.yml exec -T db psql -U openlims openlims

---

📌 Current Project Status

OpenLIMS is a production-style LIMS prototype with many production-shaped patterns already in place:

• Dockerized services
• PostgreSQL database
• Redis and Celery background jobs
• Django Channels real-time updates
• Unified My Work dashboard with bounded server-side summary aggregation
• Single-request application session bootstrap for user, feature flags, and unread-notification count
• Scalable API pagination with 50-row defaults and up to 200-row intentional collection pages
• Route-level React code splitting and production gzip/immutable asset caching
• Production PostgreSQL connection reuse and optional Redis-backed Django cache
• Targeted indexes for assigned-work and unread-notification hot paths
• Workflow-oriented Plan → Receive → Execute → Review → Report navigation
• HttpOnly browser JWT cookies with CSRF protection, refresh rotation/blacklisting, and logout invalidation
• Bearer JWT support for scripts and API clients
• Role-based permissions
• Project-scoped access control
• Backend-enforced Notebook and Registry feature flags
• Versioned /api/v1/ browser traffic with compatibility routes
• Collaborative experiment notebooks and immutable revisions
• Inventory transaction ledger and cycle-count reconciliation
• Internal workflow request intake and resource reservation
• Cross-project sample linking
• Data migration toolkit
• External sample IDs and aliases
• Audit event logging
• Reason-for-change logging
• Upload validation
• CSV and FASTA import workflows
• Flexible CSV header detection
• Instrument profile mapping
• Sequence workspaces
• Clustal Omega integration
• Local BLAST integration
• pyOpenMS mass spectrometry workflows
• Reports
• Global search
• OpenLIMS Assistant
• Optional OpenAI assistant summaries
• Optional Docker-based local Ollama assistant
• Assistant engine/model indicator in the UI
• Admin settings
• Director-controlled English/Spanish interface
• System health checks
• Production Compose deployment and Nginx frontend image
• Backend, production-build, Compose, Playwright, and performance regression CI checks

Remaining production-readiness work includes:

• Formal data-retention and archive rules across laboratory records
• SSO and optional MFA
• External/S3-compatible file storage
• More formal backup and restore automation
• Monitoring and alerting
• Expanded regression and load coverage
• Validation-readiness documentation
• Formal regulated-environment validation package

---

🗺 Roadmap

Planned and future improvements include:

• Formal record-retention and archive controls instead of destructive deletion for laboratory records
• SSO and optional MFA
• More advanced migration support for multi-file exports and system-specific API connectors
• Plate layouts and multi-sample pooling calculations on top of lineage records
• More advanced QC approval workflows
• External file storage support
• Monitoring and alerting
• Validation-readiness documentation
• Assistant calculations for safe counts, averages, percentages, and summaries
• Continued query-count, large-dataset, workflow, reporting, and browser performance regression improvements

See docs/performance_scalability_v029.md for the v0.29.0 performance and scalability implementation notes and docs/product_hardening_v0281.md for the v0.28.1 product-hardening notes.

---

🎯 Project Goals

OpenLIMS aims to be:

• Lightweight
• Self-hosted
• Configurable
• Open source and extensible for laboratory-specific workflows and integrations
• Practical for real lab workflows
• Easy to run locally or on low-cost cloud infrastructure
• Useful for small labs, research groups, and biotech teams
• A strong foundation for lab workflow automation

---

👤 Author

Eduardo L

LinkedIn: https://www.linkedin.com/in/edlemus/

---

📄 License

Copyright © 2026 Eduardo Lemus.

OpenLIMS is open-source software licensed under the Apache License 2.0. You may use, modify, and distribute the source code in accordance with the license terms.

Third-party dependencies and bundled components remain subject to their own licenses. See docs/licensing_history.md for the project's licensing history.