Docker Build Architecture

Status: Complete

Overview

This document explains the Docker build architecture for the Sasha AI Knowledge Management System, with an in‑repo UI layout (no submodules), build triggers, and deployment process.

Repository Structure

Repository Architecture

sasha-ai-knowledge-management/ (Repository)
├── .github/workflows/docker-build.yml    # Main build workflow
├── claudecodeui/                          # Application UI + server (in‑repo)
├── deployed-md-files/                     # Documentation (included in build)
├── .claude/                               # Configuration
├── VERSION                                # Version file
├── Dockerfile.sliplane                    # Alternative location (not used)
└── docs/                                 # Project documentation

claudecodeui/ (in‑repo application code)
├── src/                                   # React application source
├── server/                               # Node.js backend
├── Dockerfile.sliplane                   # Main Dockerfile for builds
├── package.json                          # Dependencies
└── (other app files)

Build Trigger Strategy

What Triggers Docker Builds

Changes to claudecodeui/** (application code)
Changes to Dockerfile.sliplane
Changes to .github/workflows/docker-build.yml
Changes to VERSION file
Git tags matching v* pattern

What Does NOT Trigger Docker Builds

Changes to deployed-md-files/** (documentation)
Changes to other documentation files
Changes to docs/ directory

Why This Design?

Documentation Separation: Documentation updates happen frequently and shouldn't require rebuilding the entire application
Efficiency: Only rebuild when the actual application code changes
Always Current: Documentation is still included in every build, just not triggering it

Build Process Flow

1. Developer Workflow

# Step 1: Make changes to the Sasha application
cd claudecodeui
# ... make changes ...
git add .
git commit -m "Add new feature X"
git push origin main

# Step 2: Push to trigger Docker build (path filters)
git push origin main

2. GitHub Actions Process

When the parent repository receives a push that affects the trigger paths:

Checkout: Repository code
Setup: Docker Buildx with multi-platform support
Version: Read version from VERSION file
Build: Multi-stage Docker build from parent context
Push: To GitHub Container Registry with multiple tags

3. Docker Build Context

The build runs from the parent repository root with access to:

Build Context: /workspace (parent repo root)
├── claudecodeui/          # ✅ Application code
├── deployed-md-files/     # ✅ Current documentation
├── .claude/               # ✅ Configuration
├── VERSION                # ✅ Version info

Dockerfile Architecture

Location and Context

Dockerfile: claudecodeui/Dockerfile.sliplane
Build Context: Parent repository root (.)
File Path: file: claudecodeui/Dockerfile.sliplane

Multi-Stage Build

# Stage 1: Dependencies
FROM node:20-alpine AS deps
# Install build tools and dependencies

# Stage 2: Build Application  
FROM node:20-alpine AS builder
# Copy source and build React application

# Stage 3: Documentation (docs-builder)
FROM node:20-alpine AS docs-builder
# Prepare documentation files

# Stage 4: Production Runtime
FROM node:20-alpine AS runner
# Final optimized image with app + docs

Key COPY Operations

# These paths work because build context is parent repo root:
COPY claudecodeui/package*.json ./          # ✅ App dependencies
COPY claudecodeui/server ./server           # ✅ Backend code
COPY deployed-md-files/docs ./docs          # ✅ Documentation  
COPY .claude /app/.claude                   # ✅ Configuration
COPY VERSION /app/VERSION                   # ✅ Version info

GitHub Actions Configuration

Workflow File Location

Path: .github/workflows/docker-build.yml
Repository: Parent repository (sasha-ai-knowledge-management)

Key Configuration

on:
  push:
    branches: [ main ]
    paths:
      - 'claudecodeui/**'        # App code changes
      - 'Dockerfile.sliplane'    # Docker changes  
      - '.github/workflows/docker-build.yml'  # Workflow changes
      - 'VERSION'                # Version changes
      # NOTE: deployed-md-files excluded
      
jobs:
  build:
    steps:
      - uses: actions/checkout@v4
          
      - name: Build and push Docker image
        uses: docker/build-push-action@v6
        with:
          context: .              # Parent repo root
          file: claudecodeui/Dockerfile.sliplane
          platforms: linux/amd64,linux/arm64

Container Registry and Tags

Registry

Location: GitHub Container Registry (ghcr.io)
Image Name: ghcr.io/wapdat/sasha-ai-knowledge-management

Automatic Tags

latest (for main branch)
v1.0.60 (from VERSION file)
1.0.60 (semantic version)
main-abc123 (branch + commit SHA)

Deployment

Pull and Run

# Pull latest image
docker pull ghcr.io/wapdat/sasha-ai-knowledge-management:latest

# Run container
docker run -d \
  -p 3005:3005 \
  -v sasha-data:/app/data \
  -v sasha-home:/home/nodejs \
  ghcr.io/wapdat/sasha-ai-knowledge-management:latest

Troubleshooting

Build Failures

Path not found errors:
- Ensure build context is parent repo root
- Verify expected files exist under claudecodeui/
Build not triggering:
- Verify changes are in trigger paths
- Check GitHub Actions tab for path filter logic