fix(docker): relocate app to /home/user/demo to preserve DeepISLES modules (#17)

* fix(docker): relocate app to /home/user/demo to preserve DeepISLES modules

Root cause: Our Dockerfile was copying src/ to /app/src/, which overwrote
DeepISLES's isles22_ensemble.py module in the base image.

Fix:
- Changed WORKDIR from /app to /home/user/demo
- Added DEEPISLES_PATH=/app env var for explicit path resolution
- Updated direct.py to check DEEPISLES_PATH first, then fallback paths

The isleschallenge/deepisles base image stores DeepISLES at:
/app/main.py
/app/src/isles22_ensemble.py
/app/weights/

Our app now lives at /home/user/demo without conflicts.

Fixes: DeepISLES modules not found on HF Spaces
See: docs/specs/09-bug-deepisles-not-installed-hf-spaces.md

* docs: update Dockerfile examples to use /home/user/demo path

Update both Dockerfile examples in 07-hf-spaces-deployment.md to reflect
the correct app location (/home/user/demo instead of /app) to prevent
overwriting DeepISLES modules in the base image.

Related: fix/deepisles-docker-path

* refactor: address CodeRabbit review feedback

- Add language specifier to code block in bug doc (markdownlint)
- Deduplicate paths in _get_deepisles_search_paths() when DEEPISLES_PATH=/app

Dockerfile

@@ -4,6 +4,9 @@
 #
 # IMPORTANT: During Docker build, GPU is NOT available.
 # All GPU operations happen at runtime only.
+#
+# CRITICAL: DeepISLES code lives at /app/src/ in the base image.
+# We install our demo at /home/user/demo to avoid overwriting DeepISLES.
 
 # NOTE: isleschallenge/deepisles only publishes 'latest' tag on Docker Hub.
 # For reproducibility, consider using a SHA digest if available:
@@ -21,20 +24,21 @@ ENV PYTHONDONTWRITEBYTECODE=1
 # Create user if not exists (DeepISLES image may already have a user)
 RUN useradd -m -u 1000 user 2>/dev/null || true
 
-# Set working directory
-WORKDIR /app
+# IMPORTANT: Use /home/user/demo for our app, NOT /app
+# /app contains DeepISLES code (main.py, src/, weights/) that we must NOT overwrite
+WORKDIR /home/user/demo
 
 # Copy requirements first for better layer caching
-COPY --chown=1000:1000 requirements.txt /app/requirements.txt
+COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
 
 # Install Python dependencies (extras only - DeepISLES image has PyTorch, nnUNet, etc.)
 RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy application source code and package files
-COPY --chown=1000:1000 pyproject.toml /app/pyproject.toml
-COPY --chown=1000:1000 README.md /app/README.md
-COPY --chown=1000:1000 src/ /app/src/
-COPY --chown=1000:1000 app.py /app/app.py
+COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
+COPY --chown=1000:1000 README.md /home/user/demo/README.md
+COPY --chown=1000:1000 src/ /home/user/demo/src/
+COPY --chown=1000:1000 app.py /home/user/demo/app.py
 
 # Install the package itself (makes stroke_deepisles_demo importable)
 # Using --no-deps since requirements.txt already installed dependencies
@@ -44,12 +48,17 @@ RUN pip install --no-cache-dir --no-deps -e .
 # This allows the app to detect runtime environment and use direct invocation
 ENV HF_SPACES=1
 ENV DEEPISLES_DIRECT_INVOCATION=1
+
+# Point to DeepISLES location for direct invocation
+# DeepISLES code is at /app in the base image
+ENV DEEPISLES_PATH=/app
+
 # Ensure HuggingFace cache uses our writable directory
-ENV HF_HOME=/app/cache
+ENV HF_HOME=/home/user/demo/cache
 
 # Create directories for data with proper permissions
-RUN mkdir -p /app/data /app/results /app/cache && \
-    chown -R 1000:1000 /app
+RUN mkdir -p /home/user/demo/data /home/user/demo/results /home/user/demo/cache && \
+    chown -R 1000:1000 /home/user/demo
 
 # Switch to non-root user (required by HF Spaces)
 USER user

docs/specs/07-hf-spaces-deployment.md

@@ -498,17 +498,33 @@ For showcasing to others. Spin up when needed, pause when done.
 
 ```dockerfile
 # Dockerfile for HF Spaces
+# CRITICAL: DeepISLES code lives at /app/src/ in the base image.
+# We install our demo at /home/user/demo to avoid overwriting DeepISLES.
 FROM isleschallenge/deepisles:latest
 
+# HF Spaces runs containers with user ID 1000
+RUN useradd -m -u 1000 user 2>/dev/null || true
+
+# IMPORTANT: Use /home/user/demo for our app, NOT /app
+WORKDIR /home/user/demo
+
 # Add our application
-COPY requirements.txt /app/
-RUN pip install -r /app/requirements.txt
+COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
 
-COPY src/ /app/src/
-COPY app.py /app/
+COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
+COPY --chown=1000:1000 src/ /home/user/demo/src/
+COPY --chown=1000:1000 app.py /home/user/demo/app.py
+RUN pip install --no-cache-dir --no-deps -e .
 
-WORKDIR /app
+# Environment variables for HF Spaces + direct invocation
+ENV HF_SPACES=1
+ENV DEEPISLES_DIRECT_INVOCATION=1
+ENV DEEPISLES_PATH=/app
+
+USER user
 EXPOSE 7860
+ENTRYPOINT []
 CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
 ```
 
@@ -681,19 +697,34 @@ uv run stroke-demo run --case sub-stroke0001
 
 ```dockerfile
 # Dockerfile
+# CRITICAL: DeepISLES code lives at /app/src/ in the base image.
+# We install our demo at /home/user/demo to avoid overwriting DeepISLES.
 FROM isleschallenge/deepisles:latest
 
+# HF Spaces runs containers with user ID 1000
+RUN useradd -m -u 1000 user 2>/dev/null || true
+
+# IMPORTANT: Use /home/user/demo for our app, NOT /app
+WORKDIR /home/user/demo
+
 # Install additional dependencies
-COPY requirements.txt /app/
-RUN pip install --no-cache-dir -r /app/requirements.txt
+COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt
+RUN pip install --no-cache-dir -r requirements.txt
 
 # Copy application code
-COPY src/ /app/src/
-COPY app.py /app/
+COPY --chown=1000:1000 pyproject.toml /home/user/demo/pyproject.toml
+COPY --chown=1000:1000 src/ /home/user/demo/src/
+COPY --chown=1000:1000 app.py /home/user/demo/app.py
+RUN pip install --no-cache-dir --no-deps -e .
 
-WORKDIR /app
-EXPOSE 7860
+# Environment variables for HF Spaces + direct invocation
+ENV HF_SPACES=1
+ENV DEEPISLES_DIRECT_INVOCATION=1
+ENV DEEPISLES_PATH=/app
 
+USER user
+EXPOSE 7860
+ENTRYPOINT []
 CMD ["python", "-m", "stroke_deepisles_demo.ui.app"]
 ```
 

docs/specs/09-bug-deepisles-not-installed-hf-spaces.md

@@ -0,0 +1,92 @@
+# Bug Spec: DeepISLES Path Conflict in Docker Build
+
+**Status:** Root Cause Found → Fix Ready
+**Priority:** P0 (Blocks inference)
+**Branch:** `fix/deepisles-docker-path`
+**Date:** 2025-12-08
+
+## Executive Summary
+
+Our Dockerfile was **overwriting DeepISLES modules** by copying our app to `/app/src/`, which is where the base image stores DeepISLES code. The fix is to install our app at `/home/user/demo` instead.
+
+## Root Cause
+
+The `isleschallenge/deepisles:latest` Docker image has this structure:
+```text
+/app/
+├── main.py
+├── requirements.txt
+├── src/                    ← DeepISLES Python modules
+│   └── isles22_ensemble.py
+└── weights/                ← Model weights (~GB)
+```
+
+Our original Dockerfile:
+```dockerfile
+FROM isleschallenge/deepisles:latest
+WORKDIR /app
+COPY src/ /app/src/         ← OVERWRITES DeepISLES modules!
+```
+
+This replaced `/app/src/isles22_ensemble.py` (DeepISLES) with `/app/src/stroke_deepisles_demo/` (our app).
+
+## The Fix
+
+1. **Changed app directory** from `/app` to `/home/user/demo`
+2. **Added `DEEPISLES_PATH=/app`** environment variable
+3. **Updated `direct.py`** to check `DEEPISLES_PATH` first
+
+### Dockerfile Changes
+```dockerfile
+# Before: WORKDIR /app
+# After:
+WORKDIR /home/user/demo
+
+# Before: COPY src/ /app/src/
+# After:
+COPY src/ /home/user/demo/src/
+
+# New:
+ENV DEEPISLES_PATH=/app
+```
+
+### direct.py Changes
+```python
+def _get_deepisles_search_paths() -> list[str]:
+    paths = []
+    # Check environment variable first (set in Dockerfile)
+    env_path = os.environ.get("DEEPISLES_PATH")
+    if env_path:
+        paths.append(env_path)
+    # Add common installation locations
+    paths.extend(["/app", "/DeepIsles", ...])
+    return paths
+```
+
+## Investigation Process
+
+1. Pulled `isleschallenge/deepisles:latest` locally
+2. Inspected WORKDIR: `/app`
+3. Listed `/app` contents: found `src/`, `weights/`, `main.py`
+4. Realized our `COPY src/ /app/src/` was overwriting DeepISLES
+
+## Files Changed
+
+- `Dockerfile` - Use `/home/user/demo`, add `DEEPISLES_PATH`
+- `src/stroke_deepisles_demo/inference/direct.py` - Dynamic search paths
+
+## Testing
+
+- All 125 unit tests pass
+- Need to test on HF Spaces to verify inference works
+
+## References
+
+- [DeepISLES GitHub](https://github.com/ezequieldlrosa/DeepIsles)
+- [Docker Hub Image](https://hub.docker.com/r/isleschallenge/deepisles)
+- [HuggingFace Docker Spaces](https://huggingface.co/docs/hub/en/spaces-sdks-docker)
+
+## Sources
+
+- [Docker Blog: Build ML Apps with HuggingFace](https://www.docker.com/blog/build-machine-learning-apps-with-hugging-faces-docker-spaces/)
+- [HuggingFace Docker Spaces Docs](https://huggingface.co/docs/hub/en/spaces-sdks-docker)

src/stroke_deepisles_demo/inference/direct.py

@@ -16,6 +16,7 @@ See:
 
 from __future__ import annotations
 
+import os
 import sys
 import time
 from dataclasses import dataclass
@@ -27,13 +28,30 @@ from stroke_deepisles_demo.inference.deepisles import find_prediction_mask
 
 logger = get_logger(__name__)
 
-# Paths where DeepISLES source might be located in the Docker image
-DEEPISLES_SEARCH_PATHS = [
-    "/app",
-    "/DeepIsles",
-    "/opt/deepisles",
-    "/home/user/DeepIsles",
-]
+
+def _get_deepisles_search_paths() -> list[str]:
+    """Get paths to search for DeepISLES modules.
+
+    Checks DEEPISLES_PATH environment variable first, then falls back to
+    common installation locations.
+    """
+    paths = []
+
+    # Check environment variable first (set in Dockerfile)
+    env_path = os.environ.get("DEEPISLES_PATH")
+    if env_path:
+        paths.append(env_path)
+
+    # Add common installation locations (excluding any already added via env var)
+    fallback_paths = [
+        "/app",  # Default location in isleschallenge/deepisles Docker image
+        "/DeepIsles",
+        "/opt/deepisles",
+        "/home/user/DeepIsles",
+    ]
+    paths.extend(p for p in fallback_paths if p not in paths)
+
+    return paths
 
 
 @dataclass(frozen=True)
@@ -54,7 +72,9 @@ def _ensure_deepisles_importable() -> str:
     Raises:
         DeepISLESError: If DeepISLES cannot be found
     """
-    for path in DEEPISLES_SEARCH_PATHS:
+    search_paths = _get_deepisles_search_paths()
+
+    for path in search_paths:
         if Path(path).exists():
             if path not in sys.path:
                 sys.path.insert(0, path)
@@ -70,7 +90,7 @@ def _ensure_deepisles_importable() -> str:
     raise DeepISLESError(
         "DeepISLES modules not found. Direct invocation requires running "
         "inside the DeepISLES Docker image. Searched paths: "
-        f"{DEEPISLES_SEARCH_PATHS}"
+        f"{search_paths}"
     )