Developer Getting Started

Quick Setup for Development

Clone the repository and set up your development environment:

git clone --recurse-submodules https://github.com/Cellular-Imaging-Amsterdam-UMC/NL-BIOMERO.git
cd NL-BIOMERO

# Setup environment
cp .env.example .env
# Edit .env with your configuration

# Start development stack
docker-compose -f docker-compose-dev.yml up -d --build

Development Features

The development compose file includes:

  • Live editing for the front-end plugin

  • Development-specific configurations

  • Special container setup for easier debugging

For detailed setup instructions, see the main README:

Containerized OMERO with BIOMERO

These scripts spin up the entire OMERO environment required for BIOMERO, and other improvements by the Core Facility Cellular Imaging.

It uses Docker Compose to setup an OMERO grid on one computer with a server, web, processor and a BIOMERO processor. If you also want to spin up a local HPC cluster with Docker Compose, to connect BIOMERO to, we host an example here.

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 is listening on the standard OMERO ports 4063 and 4064. OMERO.web is listening on port 4080 (http://localhost:4080/).

πŸš€ 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.

1. Clone and Setup

Clone this repository locally:

git clone --recurse-submodules https://github.com/Cellular-Imaging-Amsterdam-UMC/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 Automated Data Import (ADI) UI module
# ANALYZER_ENABLED=TRUE   # Enables the BIOMERO analysis UI module
# Set either to FALSE to hide that module from OMERO.web without removing containers
3. Setup Slurm Connection (Optional)

For local testing with a containerized Slurm cluster:

# Setup local Slurm cluster
cd ..
git clone https://github.com/Cellular-Imaging-Amsterdam-UMC/NL-BIOMERO-Local-Slurm
cd NL-BIOMERO-Local-Slurm
cp ~/.ssh/id_rsa.pub .
docker-compose 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
5. Deploy NL-BIOMERO

Launch the full stack:

# For development (with local builds)
docker-compose up -d --build

# For production (using pre-built images)
docker-compose -f docker-compose-from-dockerhub.yml up -d

Monitor the deployment:

docker-compose logs -f

Exit w/ CTRL + C

Verify the alias works:

# go inside your biomeroworker container:
docker-compose exec biomeroworker bash
# from inside your biomeroworker container:
ssh localslurm
exit
exit
6. Access the Interfaces

  • OMERO.web: http://localhost:4080

    • Login: root / omero (change default password)

  • Metabase: http://localhost:3000

    • Login: admin@biomero.com / b1omero (change default password)

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 - BioImage Analysis

Checkout the BIOMERO documentation for detailed usage instructions.

Quick Workflow Example:

  1. Initialize Environment:

    • Run script: slurm/init/SLURM Init environment...

    • β˜• Grab coffee (10+ min download time for a few workflow containers)

  2. Run Analysis:

    • Select your image/dataset

    • Run script: slurm/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; and Run!

    • Track your workflow status at the Status tab

  2. View Results:

    • Refresh OMERO Explore tab (in the Data tab; http://localhost:4080/webclient/)

    • Find your hello_world dataset with generated masks

πŸ› οΈ 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 Importer (ADI) and Analyzer (BIOMERO) 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

Add your institution’s logo to the login page:

  1. Place logo files in: web/local_omeroweb_edits/pretty_login/login_page_images/

  2. And just mount the file over the current image, e.g.

volumes:
      - "./web/slurm-config.ini:/opt/omero/web/OMERO.web/var/slurm-config.ini:rw"
      - "./web/local_omeroweb_edits/pretty_login/login_page_images/bioimaging.png:/opt/omero/web/venv3/lib/python3.9/site-packages/omeroweb/webclient/static/webclient/image/login_page_images/AmsterdamUMC-logo.png:ro"
      - "./web/L-Drive:/data:rw"

More details in web/README.md.

πŸ“š Additional Resources

🀝 Support

  • Issues: GitHub Issues

  • Discussions: image.sc (tag #biomero)

  • Contact: cellularimaging /at/ amsterdamumc.nl

Happy imaging! πŸ”¬βœ¨