build: docker files

Dockerfile

@@ -0,0 +1,38 @@
+FROM python:3.10-slim AS env-builder
+
+# Install system build tools
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    curl \
+    git gh \
+    vim \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install uv
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/
+
+# Clone paladin repo
+WORKDIR /deps
+RUN --mount=type=secret,id=github_token \
+    export GITHUB_TOKEN=$(cat /run/secrets/github_token) && \
+    git clone --branch dev https://oauth2:$GITHUB_TOKEN@github.com/pathology-data-mining/paladin.git
+
+# Create non-root user for runtime
+RUN useradd -m -u 1000 user
+RUN chown -R user:user /deps
+
+WORKDIR /app
+RUN chown -R user:user /app
+
+USER user
+COPY --chown=user pyproject.toml README.md ./
+COPY --chown=user src/ ./src/
+
+RUN uv sync 
+ENV PATH="/app/.venv/bin:$PATH"
+
+EXPOSE 7877
+
+# HEALTHCHECK CMD curl --fail http://localhost:8501/_stcore/health
+
+ENTRYPOINT ["gradio_app"]

README-docker.md

@@ -0,0 +1,87 @@
+# 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](#installation)
+- [Usage](#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](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html)
+
+### Installation
+
+1. Pull the image into your local Docker repository
+
+```bash
+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](https://huggingface.co/PDM-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.
+
+```bash
+export HF_TOKEN="TOKEN-FROM-HUGGINGFACE"
+```
+
+## Usage
+
+1. Start up the web app using the command
+
+```bash
+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/](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
+
+```bash
+./run_mosaic_docker.sh
+
+or
+
+./run_mosaic_docker.sh --port 7863
+```
+
+### 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.
+

run_mosaic_docker.sh

@@ -0,0 +1,52 @@
+#!/bin/bash
+
+DOCKER_NAME="tomp/mosaic-gradio"
+MOSAIC_PORT=7860
+
+SHORT_HOST=$(hostname --short)
+LONG_HOST=$(hostname --long)
+
+die () { echo "FATAL: $*"; exit 1; }
+
+usage () {
+    [[ -n $* ]] && echo "ERROR: $*"
+   cat <<END
+Usage: $0 [--port <port>]
+Options:
+    -p|--port ..... set port used to access the webapp (default: 7860)
+    -h|--help ..... print this summary
+
+This starts up a mosaic-docker container to provide a local instance
+of the Mosaic web app.
+END
+    [[ -n $* ]] && exit 1
+    exit 0
+}
+
+while [[ $# -gt 0 ]]; do
+    ARG="$1"; shift
+    case "$ARG" in
+        -p|--port) MOSAIC_PORT="${1?missing port number}"; shift;;
+        -h|--help) usage;;
+               -*) usage "Unrecognized option '$ARG'";;
+                *) usage "Unrecognized argument '$ARG'";;
+    esac
+done
+
+[[ -n $HF_TOKEN ]] || die "HF_TOKEN is undefined"
+
+echo "Access the Mosaic app at"
+echo "    http://${SHORT_HOST}:${MOSAIC_PORT}/"
+echo "or"
+echo "    http://${LONG_HOST}:${MOSAIC_PORT}/"
+echo
+echo "You may need to wait a minute or so for the models to download before the site appears."
+echo
+
+docker run -it \
+    --gpus=all --runtime=nvidia \
+    --env HF_TOKEN=${HF_TOKEN} \
+    --shm-size=500m \
+    -p ${MOSAIC_PORT}:7860 \
+    docker.io/${DOCKER_NAME}
+