Skip to content
exfabPublic

About

A high-performance Laboratory Information Management System (LIMS) for synthetic biology and automated high-throughput labs. ExLab tracks projects, strains, samples, plates, and experimental results in one place, with an OCaml backend, a Vanilla JS web UI, and a REST API for both human operators and lab automation

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

exlab

A lightweight, high-performance Laboratory Information Management System (LIMS) for synthetic biology and automated high-throughput labs. It tracks projects, strains, samples, plates and experimental results in one place, and exposes a REST API so both humans (via the web UI) and lab automation can work with the same data.

The backend is written in OCaml for type safety, with a minimal Vanilla JS frontend and PostgreSQL for storage.

License OCaml Dune PostgreSQL


Quick start (how to use it)

Option A: Docker (fastest)

docker compose up --build

This starts the app (port 8080), PostgreSQL (port 5433) and Adminer (port 8090). Open http://localhost:8080 and log in.

Option B: Local install

Prerequisites: OCaml 5.x (via opam), dune, PostgreSQL 15+.

git clone https://github.com/exfab/exlab.git
cd exlab
opam install . --deps-only
export DATABASE_URL=postgresql://user:password@localhost:5433/exlab_dev
dune exec exlab

Then open http://localhost:8080 and log in.

Logging in

On first run the database is migrated automatically. If no users exist, a default administrator account is created:

  • Email: admin@exlab.com
  • Password: admin123

Override these with the DEFAULT_ADMIN_EMAIL and DEFAULT_ADMIN_PASSWORD environment variables. To start with example projects, strains and plates, set AUTO_POPULATE_TEST_DATA=true (Docker Compose enables this by default).

Trying it with sample data: point your browser at the /docs page for an interactive API reference, and see examples/ for CSV files you can bulk import through the UI.


What it can do

Core data model

  • Projects – top-level grouping for experiments and team management; each project can have its own team of users and a dashboard.
  • Strains – organism records with lineage and cross-references to external databases (e.g. NCBI).
  • Samples – physical or virtual biological materials, linked to projects and strains, with optional parent/child (lineage) relationships.
  • Plates & Wells – multi-well plates (24, 48, 96, 384-well) with well-coordinate mapping and dashboard views.
  • Results – extensible experimental measurements built from categories and definitions (e.g. an "OD600" definition), recorded against samples or plates.
  • Analysis Runs – versioned registry of external pipeline outputs (e.g. PhenoTypic, Nextflow, custom scripts) stored in Google Cloud Storage (gs://), S3 / MinIO (s3://), or https://, keeping large Parquet/CSV/PNG deliverables in object storage while tracking manifests, checksums, canonical versions per tool, signed download URLs, and time-series plate media in ExLab.
  • Products – a catalog of standard labware and reagents.

Working with plates

  • Create plates and assign/unassign samples to wells, by coordinate or by bulk operations.
  • Layouts: upload a plate layout as an alphanumeric list (A1 → sample), a numeric list, or a visual matrix grid (see examples/plate_layout*.csv).
  • Plate planner and multi-plate planner: plan new plates / transfers and generate a transfer map in a few steps.
  • Auto-fill wells, bulk-create multiple plates at once, and export a plate's data.

Recording results

  • Define result categories and result definitions (with a short_id used in bulk uploads).
  • Add results against individual samples or entire plates.
  • Bulk-import results from CSV (see examples/example_results*.csv).
  • Export results for a project.

Bulk import & export

ExLab supports CSV (and some JSON) for high-throughput workflows. Ready-made templates live in examples/:

File Purpose
example_products.csv Bulk-import labware and reagents
example_strains.csv Bulk-import strains
example_strains.json Bulk-import strains with external DB links
example_samples.csv Bulk-create samples within a project
example_results.csv Bulk-import results against samples
example_results_plate.csv Bulk-import results against plates
plate_layout*.csv Set plate layouts (list, numeric, or matrix)
bulk_plate_creation.csv Generate multiple plates + assign samples in one upload

Access control

Role-based access control (RBAC) with four roles — Admin, Lab Manager, Project Manager, Project User — enforced through encrypted cookie sessions and email/password authentication (Argon2 hashing).

API

The server exposes a versioned REST API under /api/v1 covering all resources above. An interactive reference is served at /docs (OpenAPI/Scalar), and the spec is available at /openapi.yaml.


Configuration (Environment Variables)

Variable Default Purpose
DATABASE_URL postgresql://user:password@localhost:5433/exlab_dev PostgreSQL connection URI (or configure via DB_USER, DB_PASS, DB_HOST, DB_PORT, DB_NAME)
DB_POOL_SIZE 10 Maximum PostgreSQL connection pool size
DEFAULT_ADMIN_EMAIL admin@exlab.com Initial admin email seeded only when the users table is empty
DEFAULT_ADMIN_PASSWORD admin123 Initial admin password seeded only when the users table is empty
AUTO_POPULATE_TEST_DATA (unset) Set to true to seed example projects, strains, and plates on first boot
DREAM_SECRET (unset) Secret key used exclusively to sign and encrypt browser session cookies. Safe to rotate at any time to invalidate active user sessions
EXLAB_ENCRYPTION_KEY (dev fallback only when DREAM_SECRET is unset) Dedicated master secret for AES-256-GCM encryption at rest of external object storage credentials (gs:// / s3://) saved in PostgreSQL via the Admin Panel. Required in production (DREAM_SECRET set) before saving credentials in the Admin UI, and decoupled from DREAM_SECRET so rotating cookie secrets never invalidates stored storage keys
GCS_SIGNING_KEY_BASE64 (unset) Optional base64-encoded read-only GCP Service Account JSON key for signing gs:// download URLs and syncing bucket folders without manual Admin UI setup (can also be supplied via GCS_SIGNING_KEY_JSON or GCS_SIGNING_KEY_FILE, defaulting to ~/.config/exlab/gcs-signing-key.json if present)
S3_ACCESS_KEY_ID / S3_SECRET_ACCESS_KEY (unset) Optional S3 / MinIO access credentials for signing s3:// download URLs and syncing bucket folders without manual Admin UI setup (with optional S3_ENDPOINT_URL defaulting to https://s3.amazonaws.com and S3_REGION defaulting to us-east-1)
DREAM_VERBOSITY info Server log verbosity (error, warning, info, debug)

Project layout

src/core/      Domain types, pure logic, serialization
src/storage/   PostgreSQL access (Caqti) and code-based migrations
src/server/    Dream web framework, REST routes, auth middleware
bin/           Executable entry point (DB wait → migrate → seed → serve)
test/          Unit and integration test suites
examples/      CSV/JSON templates for bulk import

Development

dune build                 # build everything
dune exec exlab            # run the server
dune runtest -f            # run all tests (needs PostgreSQL on localhost:5433)
dune fmt                   # format with ocamlformat
dune build @fmt            # check formatting without writing

Documentation

The API is documented with an OpenAPI specification, served as an interactive reference inside the running app. Start the server, then visit http://localhost:8080/docs (or the /docs link in the frontend navigation) to browse and try every endpoint. The raw spec is available at /openapi.yaml. Sample data and CSV templates for bulk import live in examples/.


Funding

NSF ExFAB BioFoundry

This material is based on work performed at the NSF ExFAB BioFoundry and supported by the National Science Foundation under Award No. DBI-2400327. ExLab is developed in collaboration between UC Santa Barbara and UC Riverside.

About

A high-performance Laboratory Information Management System (LIMS) for synthetic biology and automated high-throughput labs. ExLab tracks projects, strains, samples, plates, and experimental results in one place, with an OCaml backend, a Vanilla JS web UI, and a REST API for both human operators and lab automation

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages