docs/specs/30-bug-hf-spaces-build-packages-dir.md

Spec #30: HF Spaces Build Error - Missing packages/ Directory

Status: 🔴 P0 BLOCKER

Issue

HuggingFace Spaces Docker build fails with:

ERROR: Invalid requirement: './packages/niivueviewer': Expected package name at the start of dependency specifier
    ./packages/niivueviewer
    ^ (from line 28 of requirements.txt)
Hint: It looks like a path. File './packages/niivueviewer' does not exist.

Root Cause Analysis

Timeline

1. PR #29 added gradio_niivueviewer custom component in packages/niivueviewer/
2. Added ./packages/niivueviewer to requirements.txt line 28 for local installs
3. Dockerfile copies requirements.txt but NOT packages/ directory
4. pip install -r requirements.txt fails because path doesn't exist

Architecture Gap

Local Development:
  requirements.txt → ./packages/niivueviewer → ✅ EXISTS

HF Spaces Docker:
  COPY requirements.txt → Container
  pip install -r requirements.txt
  → ./packages/niivueviewer → ❌ NOT COPIED

Solution Options

Option A: Copy packages/ in Dockerfile (Recommended)

Add COPY --chown=1000:1000 packages/ /home/user/demo/packages/ before pip install.

Pros:

• Simple fix
• Preserves local development workflow
• Editable install works correctly

Cons:

• Adds ~1.3MB to Docker image (compiled JS bundle)

Option B: Build wheel and include in Docker

Pre-build wheel, copy to container, install from wheel file.

Pros:

• More "production" approach

Cons:

• More complex build process
• Need to manage wheel artifacts

Option C: Separate requirements files

Create requirements-docker.txt without local path dependencies.

Pros:

• Clear separation of concerns

Cons:

• Duplicate maintenance
• Easy to drift out of sync

Recommended Fix

Option A - Simple, maintainable, aligns with how local development works.

Implementation

# BEFORE pip install, add:
COPY --chown=1000:1000 packages/ /home/user/demo/packages/

Full Dockerfile Change

# Copy requirements first for better layer caching
COPY --chown=1000:1000 requirements.txt /home/user/demo/requirements.txt

# Copy custom component packages (required for pip install)
COPY --chown=1000:1000 packages/ /home/user/demo/packages/

# Install Python dependencies into SYSTEM Python
RUN pip install --no-cache-dir -r requirements.txt

Test Plan

Level 1: Local Docker Build

docker build -t stroke-demo-test .
docker run -p 7860:7860 stroke-demo-test

Level 2: HF Spaces Deploy

Push to HF Spaces, verify build succeeds and app loads.

Level 3: Functional Test

• Upload NIfTI files
• Run segmentation
• Verify NiiVue 3D viewer renders volumes

Files to Modify

• Dockerfile - Add COPY for packages/ directory

Risk Assessment

• Low risk - Additive change, doesn't modify existing code
• Reversible - Can easily remove if issues arise

Acceptance Criteria

• HF Spaces build succeeds
• App loads without "Loading..." hang
• NiiVue viewer displays volumes correctly