README-docker.md

Mosaic: Docker deployment

The Mosaic app been packaged as a Docker image, which may be easier to use than installing the app in a Python environment.

Table of Contents

• Installation
• Usage

System requirements

Supported systems:

• Linux (x86) with GPU (NVIDIA CUDA)

Pre-requisites

You will need to have Docker or Podman installed on your system, and at least 8G of storage space for the docker image.

You will need to have the NVidia Container Toolkit installed on the machine where you want to run the Mosaic app. For instructions, see Installing the NVIDIA Container Toolkit

Installation

1. Pull the image into your local Docker repository

docker pull docker.io/tomp/mosaic-gradio

2. Set the HF_TOKEN to your HuggingFace access token

The models for Mosaic are not yet public. To access the models, you need to be a member of the Pathology Data Mining Group organization on HuggingFace.

To download the models, you need to set the HF_TOKEN environment variable to your HuggingFace access token.

If you don not already have one, create an access token by logging in to your account of HuggingFace, and clicking on the user icon at the top right corner of the site and selecting "Access Tokens". When creating the token, select all read options for your private space and the PDM-Group space.

export HF_TOKEN="TOKEN-FROM-HUGGINGFACE"

Usage

Web Application

1. Start up the web app using the command

docker run -it \
    --gpus=all --runtime=nvidia \
    --env HF_TOKEN=${HF_TOKEN} \
    --shm-size=500m \
    -p 7860:7860 \
    tomp/mosaic-gradio

2. Access the webapp at the URL http://localhost:7860/

*. You can also start up the docker container using the run_mosaic_docker.sh script in this repo. That executes the docker run command (shown above) for you, and lets you specify the port you want to use to access the app (if 7860 is not available).

To run it, you would just execute

./run_mosaic_docker.sh

or

./run_mosaic_docker.sh --port 7863

Command Line Interface (CLI)

For seamless CLI usage via Docker, use the provided mosaic wrapper script. This script automatically handles volume mounting and passes all arguments to the containerized Mosaic CLI.

Basic Usage

# Show help
./mosaic --help

# Process a single slide
./mosaic --slide-path /path/to/slide.svs \
         --output-dir /path/to/output \
         --site-type Primary \
         --cancer-subtype Unknown \
         --segmentation-config Resection

# Process multiple slides from a CSV file
./mosaic --slide-csv /path/to/slides.csv \
         --output-dir /path/to/output

# Process a breast cancer slide with IHC subtype
./mosaic --slide-path /path/to/breast_slide.svs \
         --output-dir /path/to/output \
         --site-type Primary \
         --cancer-subtype BRCA \
         --ihc-subtype "HR+/HER2-"

How it works

The mosaic wrapper script:

• Automatically mounts input slide directories and output directories into the container
• Passes through all Mosaic CLI arguments
• Handles the HF_TOKEN environment variable
• Detects and uses GPU support if available (falls back to CPU if not)

Note: When using --slide-csv, the script mounts the directory containing the CSV file. For slides referenced in the CSV, they should be in the same directory as the CSV file or in subdirectories relative to it. If slides are in different locations, you may need to modify the CSV to use relative paths or run the docker command directly with additional volume mounts.

Requirements for CLI usage

• Docker installed and running
• HF_TOKEN environment variable set (same as web app)
• NVIDIA Docker runtime for GPU support (optional, will run on CPU if not available)

Notes

• After you start up the application, it will download the necessary models from HuggingFace. This may take some time (up to a few minutes) depending on your internet connection.