Documentation Deployment Fix Summary

Status: Complete
Date: 2025-08-13
Issue Resolved: Guides and specialists not visible in UI panels

Problem

After deployment, Sasha Studio UI showed empty guides and specialists panels, even though the documentation existed in the container.

Root Cause Analysis

1. Volume Mount Overwrite: Docker COPY commands to volume-mounted paths get overwritten when persistent volumes mount at runtime
2. Path Misalignment: UI expected docs at centralized shared location but docs were scattered across different paths
3. Structure Mismatch: Guides require categorized subdirectories, specialists use flat files

Solution Implemented

Simplified Single-Location Deployment

Key Changes:

1. Dockerfile.sliplane: Copy deployed-md-files to non-mounted location

   COPY --from=docs-builder --chown=nodejs:nodejs /docs-build /app/deployed-md-files
   

2. docker-entrypoint.sh: Copy from safe location to persistent volume

   SHARED_DOCS_TARGET="/home/nodejs/all-project-files"
   if [ -d "/app/deployed-md-files/docs" ] && [ ! -d "$WORKSPACE_TARGET/docs" ]; then
       cp -r "/app/deployed-md-files/docs" "$WORKSPACE_TARGET/"
       cp -r "/app/deployed-md-files/html-static" "$WORKSPACE_TARGET/"
   fi
   

Results

• Guides Panel: Shows all categories (Business Strategy, Research, Marketing, etc.)
• Specialists Panel: Shows all specialist types
• Claude CLI Access: Working directory correctly set
• User Modifications: Preserved across container restarts
• Fresh Deployments: Documentation automatically available

Current Architecture

Container Layout:
├── /app/deployed-md-files/          # Build-time source (not volume mounted)
│   ├── docs/                       # Markdown files
│   └── html-static/                # Generated HTML
├── /home/nodejs/                   # Persistent volume mount
│   ├── projects/                   # Individual user projects
│   └── all-project-files/          # Shared documentation (runtime target)
│       ├── docs/                   # UI reads from here
│       └── html-static/            # Web assets

Technical Details

• Docker Image Version: v1.0.38+
• Deployment Method: Manual build and deploy
• Volume Configuration: 2-volume layout (home + data)
• Path Resolution: Single target on persistent volume
• User Experience: Both UI panels and Claude CLI work correctly

Key Learnings

1. Volume timing matters: Mounts happen after build, overwriting copied files
2. Path alignment is critical: All components must expect files at same location
3. Structure preservation: Different content types need different directory layouts
4. SSH debugging is essential: Direct container inspection solves deployment mysteries
5. Separate build from deploy: Isolate build issues from deployment issues

Deployment Status

• atom1: Working with guides and specialists visible
• Future deployments: Will inherit fix automatically via Docker image
• Upload issues: Noted as separate issue to address later

This fix establishes a robust, maintainable documentation deployment system for all Sasha Studio instances.