Skip to content

About

NL‑BIOMERO delivers a full containerized stack to run OMERO together with the BIOMERO 2.0 framework. It provides Docker/Podman configurations and Compose files to deploy OMERO + BIOMERO subsystems (importer, analyzer, OMERO.web plugin, databases, and auxiliary services) — the recommended starting point for a FAIR‑oriented bioimaging setup.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

 
 

Latest commit

 

History

513 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

BIOMERO Containerized OMERO with BIOMERO

NL‑BIOMERO delivers a full containerized stack to run OMERO together with the BIOMERO BIOMERO 2.0 framework. It provides Docker/Podman configurations and Compose files to deploy OMERO + BIOMERO subsystems (importer, analyzer, OMERO.web plugin, databases, and auxiliary services) — the recommended starting point for a FAIR‑oriented bioimaging setup.

BIOMERO 2.0 is described in our published paper: “BIOMERO 2.0: end-to-end FAIR infrastructure for bioimaging data import, analysis, and provenance”. See the citation guide for the full reference and guidance on citing the BIOMERO ecosystem. It transforms OMERO into a provenance‑aware, FAIR (findable, accessible, interoperable, reusable) platform by combining:

  • containerized data import and preprocessing (importer subsystem),
  • containerized or HPC‑based analysis workflows (analyzer subsystem),
  • metadata enrichment, versioning, and provenance tracking,
  • integrated workflow monitoring and dashboards.

🎥 BIOMERO videos

👉 Conceptual introduction and short technical clips

Using NL‑BIOMERO yields a unified environment where image data import, preprocessing, analysis, and provenance tracking are managed end-to-end — from raw data to processed results — in a reproducible, shareable, FAIR‑compliant infrastructure.

Architecture Overview

BIOMERO 2.0 Architecture

BIOMERO 2.0 architecture showing the integration of containerized analysis workflows (BIOMERO 1.0), preprocessing workflows (BIOMERO 2.0), and the unified OMERO.biomero web interface with OMERO.forms for metadata collection.

It uses Docker Compose to setup an OMERO grid on one computer with a server, web, processor, and a BIOMERO processor, importer and database. If you want to experiment with a local HPC cluster, an example Docker Compose setup is hosted here (or here for a GPU-enabled variant that works on WSL2/Docker Desktop).

This is an adaptation of OME's OMERO.server grid and OMERO.web (docker-compose) / OMERO.server components on multiple nodes using OMERO.grid.

  • OMERO.server listens on ports 4063 and 4064
  • OMERO.web is exposed through its Nginx frontend on port 4080 (http://localhost:4080/) in the supplied demo. Gunicorn remains internal. Sign in through this endpoint to use Open With > OME-Zarr Viewer on registered OME-Zarr Images, Plates, and Wells, including segmentation labels. See the viewer deployment and opt-in upgrade guide.

⚠️ Warning: This setup is mainly intended for demonstration or development purposes. For professional deployments, refer to the documented deployment scenarios in our documentation and see the deployment scenarios folder. We strongly discourage running Slurm inside Docker Compose for production; connect BIOMERO to a real HPC cluster to ensure stability, full feature support, and performance.


🚀 Platform-Specific Deployment

Windows (Docker Desktop)

Follow the Quickstart section below for Windows deployment with Docker Desktop.

Ubuntu/Linux

For Ubuntu/Linux deployments (with SSL support), see our dedicated guide: 📖 Ubuntu/Linux Deployment Guide


Quickstart (Windows)

Note: This quickstart is based on Windows Docker Desktop and uses host.docker.internal to communicate between local clusters. Linux users should refer to the Ubuntu/Linux guide.

0. Prerequisites

  • Docker Desktop
  • Git for Windows
  • a SSH keypair (@ ~/.ssh/id_rsa)
  • Powershell

Then do all these steps in Powershell:

1. Clone and Setup

Clone this repository locally:

git clone --recursive https://github.com/NL-BioImaging/NL-BIOMERO.git
cd NL-BIOMERO

2. Configure Environment

First, customize your environment file .env:

# Edit .env with your secure passwords and configuration
# Edit biomeroworker/slurm-config.ini if you need different BIOMERO settings
# Toggle UI components (both default to TRUE):
# IMPORTER_ENABLED=TRUE   # Enables the BIOMERO.importer UI module
# ANALYZER_ENABLED=TRUE   # Enables the BIOMERO.analyzer UI module
# BIOMERO_ZARR_VIEWER_ENABLED=TRUE  # Enabled in the supplied demo configuration
# BIOMERO_WEB_HOST_PORT=4080  # The single browser-facing OMERO.web endpoint
# BIOMERO_SHALLOW_ZARR=FALSE  # Opt in to canonical-cache/shallow-result handling
# BIOMERO_SHALLOW_ZARR_WORKERS=4  # Optional importer-side identity workers
# BIOMERO_DETACHED_WORKFLOWS=TRUE  # Enabled in this fresh demo configuration
# BIOMERO_MAX_ACTIVE_WORKFLOWS=4  # Maximum concurrent non-batched runs
# BIOMERO_SUPERVISOR_POLL_SECONDS=10  # Queue polling interval
# BIOMERO_SUPERVISOR_STARTUP_GRACE_SECONDS=60  # Delay before recovery polling
# OMERO_SCRIPTS_TIMEOUT=3600000  # Normal OMERO default: 1 hour
# OMERO_SESSIONS_TIMEOUT=600000  # Normal OMERO default: 10 minutes idle
# OMERO_WEB_SESSION_COOKIE_AGE=86400  # Normal OMERO.web default: 1 day
# OMERO_WEB_SESSION_EXPIRE_AT_BROWSER_CLOSE=false  # Local browser-cookie policy
# Set IMPORTER_ENABLED or ANALYZER_ENABLED to FALSE to hide that UI module
# from OMERO.web without removing containers

BIOMERO_SHALLOW_ZARR is effective only when IMPORTER_ENABLED=TRUE. With the flag absent or false, Image Transfer and Import Results keep their established export/import behavior. BIOMERO_SHALLOW_ZARR_WORKERS is an importer-service setting and defaults to 4 in this deployment. Installations may override it to match their local CPU and storage capacity. It is not forwarded to OMERO scripts and is unused while shallow mode is disabled.

The supplied demo selects COMPOSE_PROFILES=IMPORTER_ENABLED and exposes all OMERO.web traffic through its Nginx frontend. Existing deployments upgrading their images keep the viewer disabled when BIOMERO_ZARR_VIEWER_ENABLED is missing, empty or false. To opt in, enable the flag and configure the authenticated Nginx storage route. The frontend is also used when the viewer is disabled, while the HTTPS scenario extends its existing Nginx frontend. Preserve your current environment and site settings when upgrading. See the viewer guide.

New in NL-BIOMERO 1.8 — opt-in detached-workflow feature: The BIOMERO_DETACHED_WORKFLOWS feature flag allows an accepted workflow to continue after the requesting OMERO session ends. The fresh demo configuration supplied in this repository enables the feature to showcase the complete stack. Existing and custom deployments remain on the established inline behavior when the feature flag is absent or set to FALSE; administrators must explicitly enable it during their upgrade.

With detached mode enabled, the complete Slurm runtime no longer requires an open browser, an extended OMERO session, or a seven-day web cookie. With detached mode disabled, the script runs inline: the user must keep the session active and administrators may still need longer timeouts for long workflows. The other detached settings control concurrency, queue polling, and startup grace. Set OMERO_WEB_SESSION_EXPIRE_AT_BROWSER_CLOSE according to local browser-session policy. See the detached workflows administrator guide for configuration and operational details.

3. Setup Slurm Connection (Optional)

For local testing with a containerized Slurm cluster:

# Setup local Slurm cluster
cd ..
git clone https://github.com/NL-BioImaging/NL-BIOMERO-Local-Slurm
cd NL-BIOMERO-Local-Slurm
# (or use NL-BIOMERO-Local-Slurm-GPU for GPU support on WSL2/Docker Desktop:
#  https://github.com/Cellular-Imaging-Amsterdam-UMC/NL-BIOMERO-Local-Slurm-GPU)
cp ~/.ssh/id_rsa.pub .
docker compose -f .\docker-compose-from-dockerhub.yml up -d --build  
cd ../NL-BIOMERO

4. Configure SSH Access

Test Slurm connectivity:

# from your host machine:
ssh -i ~/.ssh/id_rsa -p 2222 -o StrictHostKeyChecking=no slurm@localhost
# or from inside your biomeroworker container:
ssh -i ~/.ssh/id_rsa -p 2222 -o StrictHostKeyChecking=no slurm@host.docker.internal
exit

If successful, create an SSH alias:

cp ssh.config.example ~/.ssh/config

If not successful, try forcing ownership and permissions (and then try ssh again):

# from your host machine:
docker exec -it slurmctld bash -c "chown -R slurm:slurm /home/slurm/.ssh && chmod 700 /home/slurm/.ssh && chmod 600 /home/slurm/.ssh/authorized_keys" 

5. Deploy NL-BIOMERO

Launch the full stack:

# For development (with local builds)
docker-compose build --no-cache
# Then run in the background
docker-compose up -d

# OR 

# For production (using pre-built images)
docker-compose --env-file .\.env -f .\deployment_scenarios\docker-compose-from-dockerhub.yml pull
# wait ~10 min for download
docker-compose --env-file .\.env -f .\deployment_scenarios\docker-compose-from-dockerhub.yml up -d

Monitor the deployment:

docker-compose logs -f

# OR

docker-compose --env-file .\.env -f .\deployment_scenarios\docker-compose-from-dockerhub.yml logs -f

Exit w/ CTRL + C

Verify the alias works:

# go inside your biomeroworker container:
docker-compose exec biomeroworker bash
# OR
docker-compose --env-file .\.env -f .\deployment_scenarios\docker-compose-from-dockerhub.yml exec biomeroworker bash 

# from inside your biomeroworker container:
ssh localslurm
exit
exit

6. Access the Interfaces

If you disabled modules via IMPORTER_ENABLED=FALSE or ANALYZER_ENABLED=FALSE, the corresponding UI tabs/panels won't appear.


📊 Data Import

To get started with data:

  1. Web Import: Use the Importer tab in OMERO.biomero at http://localhost:4080/omero_biomero/biomero/
  2. OMERO.insight: Download the desktop client
    • Connect to localhost:4063
    • Login as root / omero

BIOMERO BIOMERO - BioImage Analysis

Checkout the BIOMERO documentation for detailed usage instructions.

Quick Workflow Example:

  1. Initialize Environment:

    • Run script: biomero > admin > SLURM Init environment...
    • ☕ Grab coffee (10+ min download time for a few workflow containers)
  2. Run Analysis:

    • Select your image/dataset
    • Run script: biomero > __workflows >SLURM Run Workflow...
    • Configure import: Change Import into NEW Dataset → hello_world
    • Select workflow: e.g., cellpose
    • Set parameters: nucleus channel, GPU settings, etc.

OR

  1. OMERO.biomero Analyzer UI:

    • Use the Analyzer tab at http://localhost:4080/omero_biomero/biomero/?tab=biomero
    • Select your workflow: e.g., Cellpose
    • Add Dataset, select the image(s) you want to segment
    • Fill in the workflow parameters in tab 2, e.g. nuclei channel 3
    • Select desired output target, e.g. Select Dataset hello_world again (don't forget to press ENTER if you're typing it); and Run!
    • Track your workflow status at the Status tab
  2. View Results:


🛠️ Container Management

Basic Operations

# Stop the cluster
docker-compose down

# Remove with volumes (⚠️ deletes data)
docker-compose down --volumes

# Rebuild single container
docker-compose up -d --build --force-recreate <container-name>

# Access container shell
docker-compose exec <container-name> bash

Useful Container Names

  • omeroserver - OMERO server
  • omeroweb - Web interface
  • biomeroworker - BIOMERO processor
  • metabase - Analytics dashboard

🔧 Configuration

Slurm Connection Requirements

See BIOMERO documentation for comprehensive setup details.

Essential Components:

  • SSH Configuration: Headless SSH to Slurm server
    • Server IP/hostname
    • SSH port (usually 22)
    • Username and SSH keys
    • Alias configuration in ~/.ssh/config
  • Slurm Configuration: Edit biomeroworker/slurm-config.ini
    • SSH alias (e.g., localslurm)
    • Storage paths: slurm_data_path, slurm_images_path, slurm_script_path

Linux Considerations

  • SSH permissions: chmod -R 777 ~/.ssh before deployment
  • Use postgres:16-alpine for better compatibility
  • See Ubuntu/Linux guide for detailed instructions

🎨 Frontend Customizations

This deployment includes several UI enhancements:

  • 🧩 OMERO.biomero Plugin: Unified BIOMERO.importer and BIOMERO.analyzer tabs
  • 📝 OMERO.forms: Create custom metadata forms for users to fill in
  • 🔘 Better Buttons: Improved some button design and accessibility
  • 🎭 Pretty Login: Minor enhanced login page aesthetics

The previous codename "CANVAS" has been replaced by the official name OMERO.biomero.

Custom Institution Branding

By default, BIOMERO 2.0 uses NL-BioImaging branding. To customize:

Change banner logo: Mount your logo over the banner image

- "./your-logo.png:/opt/omero/web/venv3/lib/python3.12/site-packages/omeroweb/webclient/static/webclient/image/login_page_images/nl-bioimaging-banner.png:ro"

Change footer logo: Mount your logo over the footer image

- "./your-logo.png:/opt/omero/web/venv3/lib/python3.12/site-packages/omeroweb/webclient/static/webclient/image/login_page_images/NL-BIoImaging-logo.jpg:ro"

Change footer text/colors/design: Create custom login.html template with inline CSS and mount it

- "./custom-login.html:/opt/omero/web/venv3/lib/python3.12/site-packages/omeroweb/webclient/templates/webclient/login.html:ro"

Restart container after changes: docker-compose down omeroweb && docker-compose up -d omeroweb

See web/local_omeroweb_edits/pretty_login/login-amsterdamumc.html for complete template example.

More details in web/README.md.


� Development

Building Documentation

Quick local preview (working directory)

To preview your uncommitted changes instantly:

cd "NL-BIOMERO\docs"
.\venv\Scripts\sphinx-build.exe -b html . _build_local

Then open docs/_build_local/sysadmin/omero-biomero-admin.html (or any page) in a browser.

Note: sphinx-multiversion builds from git commits only — it will not pick up uncommitted edits. Always use sphinx-build for a quick preview while authoring.

Full versioned build (all tags + branches)

Once your changes are committed, rebuild the complete versioned site:

cd "NL-BIOMERO\docs"
Remove-Item -Recurse -Force _build -ErrorAction SilentlyContinue
.\venv\Scripts\sphinx-multiversion.exe . _build
Copy-Item assets/gh-pages-redirect.html _build/index.html
$latestTag = (git tag -l "v*.*.*" | Where-Object { $_ -match "^v[0-9]+\.[0-9]+\.[0-9]+$" } | Sort-Object {[version]($_ -replace '^v','')} -Descending | Select-Object -First 1)
if ($latestTag) { Copy-Item "_build/$latestTag" "_build/latest" -Recurse; Write-Host "Created latest directory pointing to $latestTag" }

This builds all tagged versions and branches, then creates a latest/ directory pointing to the newest release tag.


📚� Additional Resources


🤝 Support

  • Issues: GitHub Issues
  • Discussions: image.sc (tag #biomero)
  • Contact: cellularimaging /at/ amsterdamumc.nl

Happy imaging! 🔬✨

About

NL‑BIOMERO delivers a full containerized stack to run OMERO together with the BIOMERO 2.0 framework. It provides Docker/Podman configurations and Compose files to deploy OMERO + BIOMERO subsystems (importer, analyzer, OMERO.web plugin, databases, and auxiliary services) — the recommended starting point for a FAIR‑oriented bioimaging setup.

Topics

Resources

Stars

13 stars

Watchers

1 watching

Forks

Releases

Used by

Contributors

Languages