Improve Docker configuration for HuggingFace cache and permissions

- Add HF_HOME and TRANSFORMERS_CACHE env vars with mounted cache directory
- Increase shared memory from 500m to 3G
- Add HF_TOKEN validation to all Docker targets
- Create output directory before Docker runs to ensure proper ownership
- Add ARGS variable support for passing extra arguments to mosaic
- Update volume mount paths to use /mnt/slides, /mnt/data, /mnt/output
- Add docker-run-cli target for running arbitrary mosaic CLI commands
- Fix mosaic script to use mskmind/mosaic image and consistent formatting

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Makefile

@@ -1,4 +1,4 @@
-.PHONY: help install install-dev test test-coverage test-verbose lint format clean docker-build docker-run docker-push docker-clean run-ui run-cli
+.PHONY: help install install-dev test test-coverage test-verbose lint format clean docker-build docker-run docker-run-cli docker-push docker-clean run-ui run-cli
 
 # Default target
 .DEFAULT_GOAL := help
@@ -75,14 +75,19 @@ run-ui: ## Launch Gradio web interface
 run-ui-public: ## Launch Gradio web interface with public sharing
 	$(PYTHON) -m mosaic.gradio_app --share
 
-run-single: ## Run single slide analysis (usage: make run-single SLIDE=path/to/slide.svs OUTPUT=output_dir)
-	$(PYTHON) -m mosaic.gradio_app --slide-path $(SLIDE) --output-dir $(OUTPUT)
+run-single: ## Run single slide analysis (usage: make run-single SLIDE=path/to/slide.svs OUTPUT=output_dir [ARGS="--extra-args"])
+	$(PYTHON) -m mosaic.gradio_app --slide-path $(SLIDE) --output-dir $(OUTPUT) $(ARGS)
 
-run-batch: ## Run batch analysis from CSV (usage: make run-batch CSV=settings.csv OUTPUT=output_dir)
-	$(PYTHON) -m mosaic.gradio_app --slide-csv $(CSV) --output-dir $(OUTPUT)
+run-batch: ## Run batch analysis from CSV (usage: make run-batch CSV=settings.csv OUTPUT=output_dir [ARGS="--extra-args"])
+	$(PYTHON) -m mosaic.gradio_app --slide-csv $(CSV) --output-dir $(OUTPUT) $(ARGS)
 
 ##@ Docker
 
+# Docker run options matching the mosaic entrypoint script
+DOCKER_GPU_ARGS := --gpus=all --runtime=nvidia
+HF_CACHE_DIR := $(HOME)/.cache/huggingface
+DOCKER_COMMON_ARGS := --shm-size=3G --env HF_TOKEN="$(HF_TOKEN)" --env HF_HOME=/mnt/hf_cache --env TRANSFORMERS_CACHE=/mnt/hf_cache --user $(shell id -u):$(shell id -g) -v $(HF_CACHE_DIR):/mnt/hf_cache
+
 docker-build: ## Build Docker image with SSH forwarding
 	@echo "Building Docker image with SSH authentication..."
 	@./build.sh
@@ -96,38 +101,65 @@ docker-build-no-cache: ## Build Docker image without cache
 	eval "$$(ssh-agent -k)"
 
 docker-run: ## Run Docker container (web UI mode)
+	@test -n "$(HF_TOKEN)" || (echo "Error: HF_TOKEN environment variable is not set" && exit 1)
 	docker run -it --rm \
-		--gpus all \
+		$(DOCKER_GPU_ARGS) \
+		$(DOCKER_COMMON_ARGS) \
 		-p 7860:7860 \
-		-v $(PWD)/data:/app/data \
-		-v $(PWD)/output:/app/output \
+		-v $(PWD)/data:/mnt/data:ro \
+		-v $(PWD)/output:/mnt/output \
 		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG)
 
-docker-run-single: ## Run Docker container (single slide mode)
+docker-run-cli: ## Run Docker container with mosaic CLI (usage: make docker-run-cli ARGS="--help")
+	@test -n "$(HF_TOKEN)" || (echo "Error: HF_TOKEN environment variable is not set" && exit 1)
 	docker run -it --rm \
-		--gpus all \
-		-v $(PWD)/data:/app/data \
-		-v $(PWD)/output:/app/output \
+		$(DOCKER_GPU_ARGS) \
+		$(DOCKER_COMMON_ARGS) \
+		-v $(PWD)/data:/mnt/data:ro \
+		-v $(PWD)/output:/mnt/output \
+		--entrypoint mosaic \
 		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG) \
-		--slide-path /app/data/$(SLIDE) \
-		--output-dir /app/output
+		$(ARGS)
 
-docker-run-batch: ## Run Docker container (batch mode)
+docker-run-single: ## Run Docker container (single slide mode, usage: make docker-run-single SLIDE=path/to/slide.svs [ARGS="--extra-args"])
+	@test -n "$(HF_TOKEN)" || (echo "Error: HF_TOKEN environment variable is not set" && exit 1)
+	@test -n "$(SLIDE)" || (echo "Error: SLIDE variable is required" && exit 1)
+	@mkdir -p $(PWD)/output
+	docker run -it --rm \
+		$(DOCKER_GPU_ARGS) \
+		$(DOCKER_COMMON_ARGS) \
+		-v $(dir $(abspath $(SLIDE))):/mnt/slides:ro \
+		-v $(PWD)/output:/mnt/output \
+		--entrypoint mosaic \
+		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG) \
+		--slide-path /mnt/slides/$(notdir $(SLIDE)) \
+		--output-dir /mnt/output \
+		$(ARGS)
+
+docker-run-batch: ## Run Docker container (batch mode, usage: make docker-run-batch CSV=path/to/slides.csv [ARGS="--extra-args"])
+	@test -n "$(HF_TOKEN)" || (echo "Error: HF_TOKEN environment variable is not set" && exit 1)
+	@test -n "$(CSV)" || (echo "Error: CSV variable is required" && exit 1)
+	@mkdir -p $(PWD)/output
 	docker run -it --rm \
-		--gpus all \
-		-v $(PWD)/data:/app/data \
-		-v $(PWD)/output:/app/output \
+		$(DOCKER_GPU_ARGS) \
+		$(DOCKER_COMMON_ARGS) \
+		-v $(dir $(abspath $(CSV))):/mnt/data:ro \
+		-v $(PWD)/output:/mnt/output \
+		--entrypoint mosaic \
 		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG) \
-		--slide-csv /app/data/$(CSV) \
-		--output-dir /app/output
+		--slide-csv /mnt/data/$(notdir $(CSV)) \
+		--output-dir /mnt/output \
+		$(ARGS)
 
 docker-shell: ## Open shell in Docker container
+	@test -n "$(HF_TOKEN)" || (echo "Error: HF_TOKEN environment variable is not set" && exit 1)
 	docker run -it --rm \
-		--gpus all \
-		-v $(PWD)/data:/app/data \
-		-v $(PWD)/output:/app/output \
-		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG) \
-		/bin/bash
+		$(DOCKER_GPU_ARGS) \
+		$(DOCKER_COMMON_ARGS) \
+		-v $(PWD)/data:/mnt/data:ro \
+		-v $(PWD)/output:/mnt/output \
+		--entrypoint /bin/bash \
+		$(DOCKER_IMAGE_NAME):$(DOCKER_TAG)
 
 docker-tag: ## Tag Docker image for registry
 	docker tag $(DOCKER_IMAGE_NAME):$(DOCKER_TAG) $(DOCKER_REGISTRY)/$(DOCKER_IMAGE_NAME):$(DOCKER_TAG)

mosaic

@@ -20,10 +20,14 @@
 #       in the same directory tree. Slides can be in subdirectories relative to
 #       the CSV file location.
 
-DOCKER_IMAGE="tomp/mosaic-gradio"
+DOCKER_IMAGE="mskmind/mosaic"
 USE_GPU=true
+HF_CACHE_DIR="${HOME}/.cache/huggingface"
 
-die () { echo "FATAL: $*" >&2; exit 1; }
+die() {
+  echo "FATAL: $*" >&2
+  exit 1
+}
 
 # Check if Docker is available
 command -v docker >/dev/null 2>&1 || die "Docker is not installed or not in PATH"
@@ -31,13 +35,16 @@ command -v docker >/dev/null 2>&1 || die "Docker is not installed or not in PATH
 # Check if HF_TOKEN is set
 [[ -n $HF_TOKEN ]] || die "HF_TOKEN environment variable is not set. Please set it to your HuggingFace access token."
 
+# Create HuggingFace cache directory if it doesn't exist
+mkdir -p "$HF_CACHE_DIR"
+
 # Check if nvidia runtime is available
 if docker info 2>/dev/null | grep -q nvidia; then
-    USE_GPU=true
+  USE_GPU=true
 else
-    echo "Warning: NVIDIA Docker runtime not detected. Running without GPU support." >&2
-    echo "         To enable GPU support, install the NVIDIA Container Toolkit." >&2
-    USE_GPU=false
+  echo "Warning: NVIDIA Docker runtime not detected. Running without GPU support." >&2
+  echo "         To enable GPU support, install the NVIDIA Container Toolkit." >&2
+  USE_GPU=false
 fi
 
 # Parse arguments to identify paths that need to be mounted
@@ -45,73 +52,75 @@ VOLUME_MOUNTS=()
 ARGS=()
 
 while [[ $# -gt 0 ]]; do
-    ARG="$1"
-    case "$ARG" in
-        --slide-path)
-            shift
-            SLIDE_PATH="$1"
-            if [[ -n "$SLIDE_PATH" ]]; then
-                # Convert to absolute path
-                SLIDE_PATH=$(readlink -f "$SLIDE_PATH")
-                SLIDE_DIR=$(dirname "$SLIDE_PATH")
-                SLIDE_FILE=$(basename "$SLIDE_PATH")
-                # Mount the directory containing the slide
-                VOLUME_MOUNTS+=("-v" "$SLIDE_DIR:/mnt/slides:ro")
-                # Pass the container path to mosaic
-                ARGS+=("--slide-path" "/mnt/slides/$SLIDE_FILE")
-            fi
-            shift
-            ;;
-        --slide-csv)
-            shift
-            CSV_PATH="$1"
-            if [[ -n "$CSV_PATH" ]]; then
-                # Convert to absolute path
-                CSV_PATH=$(readlink -f "$CSV_PATH")
-                CSV_DIR=$(dirname "$CSV_PATH")
-                CSV_FILE=$(basename "$CSV_PATH")
-                # Mount the parent directory of CSV (to allow slides in subdirs)
-                # This allows the CSV to reference slides with relative paths
-                VOLUME_MOUNTS+=("-v" "$CSV_DIR:/mnt/data:ro")
-                # Pass the container path to mosaic
-                ARGS+=("--slide-csv" "/mnt/data/$CSV_FILE")
-            fi
-            shift
-            ;;
-        --output-dir)
-            shift
-            OUTPUT_DIR="$1"
-            if [[ -n "$OUTPUT_DIR" ]]; then
-                # Convert to absolute path and create if it doesn't exist
-                mkdir -p "$OUTPUT_DIR"
-                OUTPUT_DIR=$(readlink -f "$OUTPUT_DIR")
-                # Mount the output directory
-                VOLUME_MOUNTS+=("-v" "$OUTPUT_DIR:/mnt/output")
-                # Pass the container path to mosaic
-                ARGS+=("--output-dir" "/mnt/output")
-            fi
-            shift
-            ;;
-        *)
-            # Pass through all other arguments
-            ARGS+=("$ARG")
-            shift
-            ;;
-    esac
+  ARG="$1"
+  case "$ARG" in
+  --slide-path)
+    shift
+    SLIDE_PATH="$1"
+    if [[ -n "$SLIDE_PATH" ]]; then
+      # Convert to absolute path
+      SLIDE_PATH=$(readlink -f "$SLIDE_PATH")
+      SLIDE_DIR=$(dirname "$SLIDE_PATH")
+      SLIDE_FILE=$(basename "$SLIDE_PATH")
+      # Mount the directory containing the slide
+      VOLUME_MOUNTS+=("-v" "$SLIDE_DIR:/mnt/slides:ro")
+      # Pass the container path to mosaic
+      ARGS+=("--slide-path" "/mnt/slides/$SLIDE_FILE")
+    fi
+    shift
+    ;;
+  --slide-csv)
+    shift
+    CSV_PATH="$1"
+    if [[ -n "$CSV_PATH" ]]; then
+      # Convert to absolute path
+      CSV_PATH=$(readlink -f "$CSV_PATH")
+      CSV_DIR=$(dirname "$CSV_PATH")
+      CSV_FILE=$(basename "$CSV_PATH")
+      # Mount the parent directory of CSV (to allow slides in subdirs)
+      # This allows the CSV to reference slides with relative paths
+      VOLUME_MOUNTS+=("-v" "$CSV_DIR:/mnt/data:ro")
+      # Pass the container path to mosaic
+      ARGS+=("--slide-csv" "/mnt/data/$CSV_FILE")
+    fi
+    shift
+    ;;
+  --output-dir)
+    shift
+    OUTPUT_DIR="$1"
+    if [[ -n "$OUTPUT_DIR" ]]; then
+      # Convert to absolute path and create if it doesn't exist
+      mkdir -p "$OUTPUT_DIR"
+      OUTPUT_DIR=$(readlink -f "$OUTPUT_DIR")
+      # Ensure directory is writable by current user
+      chmod u+rwx "$OUTPUT_DIR" 2>/dev/null || true
+      # Mount the output directory
+      VOLUME_MOUNTS+=("-v" "$OUTPUT_DIR:/mnt/output")
+      # Pass the container path to mosaic
+      ARGS+=("--output-dir" "/mnt/output")
+    fi
+    shift
+    ;;
+  *)
+    # Pass through all other arguments
+    ARGS+=("$ARG")
+    shift
+    ;;
+  esac
 done
 
 # Remove duplicate volume mounts
 UNIQUE_MOUNTS=$(printf '%s\n' "${VOLUME_MOUNTS[@]}" | awk '!seen[$0]++')
 VOLUME_ARGS=()
 while IFS= read -r mount; do
-    [[ -n "$mount" ]] && VOLUME_ARGS+=("$mount")
-done <<< "$UNIQUE_MOUNTS"
+  [[ -n "$mount" ]] && VOLUME_ARGS+=("$mount")
+done <<<"$UNIQUE_MOUNTS"
 
 # Run the Docker container with the mosaic CLI
 # Override the entrypoint to run mosaic command instead of gradio_app
 GPU_ARGS=()
 if [ "$USE_GPU" = true ]; then
-    GPU_ARGS+=("--gpus=all" "--runtime=nvidia")
+  GPU_ARGS+=("--gpus=all" "--runtime=nvidia")
 fi
 
 # Get current user ID and group ID to ensure output files have correct ownership
@@ -119,11 +128,14 @@ USER_ID=$(id -u)
 GROUP_ID=$(id -g)
 
 docker run --rm \
-    "${GPU_ARGS[@]}" \
-    --user "${USER_ID}:${GROUP_ID}" \
-    --env HF_TOKEN="${HF_TOKEN}" \
-    --shm-size=500m \
-    "${VOLUME_ARGS[@]}" \
-    --entrypoint mosaic \
-    "$DOCKER_IMAGE" \
-    "${ARGS[@]}"
+  "${GPU_ARGS[@]}" \
+  --user "${USER_ID}:${GROUP_ID}" \
+  --env HF_TOKEN="${HF_TOKEN}" \
+  --env HF_HOME=/mnt/hf_cache \
+  --env TRANSFORMERS_CACHE=/mnt/hf_cache \
+  --shm-size=3G \
+  -v "${HF_CACHE_DIR}:/mnt/hf_cache" \
+  "${VOLUME_ARGS[@]}" \
+  --entrypoint mosaic \
+  "$DOCKER_IMAGE" \
+  "${ARGS[@]}"