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.
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.
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
4063and4064 - 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.
Follow the Quickstart section below for Windows deployment with Docker Desktop.
For Ubuntu/Linux deployments (with SSL support), see our dedicated guide: 📖 Ubuntu/Linux Deployment Guide
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.
- Docker Desktop
- Git for Windows
- a SSH keypair (@ ~/.ssh/id_rsa)
- Powershell
Then do all these steps in Powershell:
Clone this repository locally:
git clone --recursive https://github.com/NL-BioImaging/NL-BIOMERO.git
cd NL-BIOMEROFirst, 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 containersBIOMERO_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_WORKFLOWSfeature 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 toFALSE; 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.
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-BIOMEROTest 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
exitIf successful, create an SSH alias:
cp ssh.config.example ~/.ssh/configIf 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" 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 -dMonitor the deployment:
docker-compose logs -f
# OR
docker-compose --env-file .\.env -f .\deployment_scenarios\docker-compose-from-dockerhub.yml logs -fExit 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- OMERO.web: http://localhost:4080
- Login:
root/omero(change default password)
- Login:
- Metabase: http://localhost:3000
- Login:
admin@biomero.com/b1omero(change default password)
- Login:
If you disabled modules via IMPORTER_ENABLED=FALSE or ANALYZER_ENABLED=FALSE, the corresponding UI tabs/panels won't appear.
To get started with data:
- Web Import: Use the Importer tab in OMERO.biomero at http://localhost:4080/omero_biomero/biomero/
- OMERO.insight: Download the desktop client
- Connect to
localhost:4063 - Login as
root/omero
- Connect to
Checkout the BIOMERO documentation for detailed usage instructions.
-
Initialize Environment:
- Run script:
biomero>admin>SLURM Init environment... - ☕ Grab coffee (10+ min download time for a few workflow containers)
- Run script:
-
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
-
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_worldagain (don't forget to press ENTER if you're typing it); and Run! - Track your workflow status at the
Statustab
-
View Results:
- Refresh OMERO
Exploretab (in the Data tab; http://localhost:4080/webclient/) - Find your
hello_worlddataset with generated masks
- Refresh OMERO
# 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> bashomeroserver- OMERO serveromeroweb- Web interfacebiomeroworker- BIOMERO processormetabase- Analytics dashboard
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
- SSH alias (e.g.,
- SSH permissions:
chmod -R 777 ~/.sshbefore deployment - Use
postgres:16-alpinefor better compatibility - See Ubuntu/Linux guide for detailed instructions
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.
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.
To preview your uncommitted changes instantly:
cd "NL-BIOMERO\docs"
.\venv\Scripts\sphinx-build.exe -b html . _build_localThen open docs/_build_local/sysadmin/omero-biomero-admin.html (or any page) in a browser.
Note:
sphinx-multiversionbuilds from git commits only — it will not pick up uncommitted edits. Always usesphinx-buildfor a quick preview while authoring.
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.
- 📖 Ubuntu/Linux Deployment - Production deployment guide
- 🧬 BIOMERO Documentation - Analysis workflows
- 🏗️ Local Slurm Cluster - Testing environment (CPU-only)
- 🏗️ Local Slurm Cluster (GPU) - Testing environment with GPU node (WSL2/Docker Desktop)
- 🔬 OMERO Documentation - Core platform docs
- Issues: GitHub Issues
- Discussions: image.sc (tag #biomero)
- Contact: cellularimaging /at/ amsterdamumc.nl
Happy imaging! 🔬✨
