Last updated: Aug 12, 2025, 01:09 PM UTC

Docker Deployment Plan for Sasha Studio

Generated: 2025-01-07 15:45 UTC
Status: In Progress
Version: 1.0

Overview

This document outlines the comprehensive plan for containerizing Sasha Studio using Docker and preparing it for eventual deployment to Google Cloud Platform (GCP) Cloud Run.

Current Progress

Completed Tasks

  1. Production Dockerfile Created

    • Multi-stage build with deps, builder, and runner stages
    • Alpine Linux base for minimal size
    • Non-root user (nodejs:1001) for security
    • Build tools included for npm package installation
    • Security hardening implemented
    • Health checks configured

  2. Docker Compose Configuration

    • Production and development profiles
    • Persistent volumes for data, uploads, docs, node_modules
    • Security options (no-new-privileges, capability drops)
    • Resource limits configured
    • Health checks and logging

  3. Docker Ignore File

    • Optimized build context
    • Excludes unnecessary files
    • Keeps essential application files

  4. Build and Test Scripts

    • docker-build.sh: Automated build script with production/dev targets
    • docker-test.sh: Comprehensive testing script
    • npm-install-docker.sh: Install packages in running container

In Progress Tasks

  1. Update Server for Environment Variables
    • Need to modify server/index.js to use environment variables
    • Add /api/health endpoint
    • Configure security middleware based on env vars

Pending Tasks

  1. Test Container Locally
  2. Verify Docs Directory Permissions
  3. Document Local Testing Process
  4. Create Development Dockerfile
  5. Implement Claude CLI Installation
  6. Configure GCP Cloud Run Deployment

Technical Architecture

Container Structure

┌─────────────────────────────────────┐
│         Multi-Stage Build            │
├─────────────────────────────────────┤
│ Stage 1: deps                        │
│ - Install build tools                │
│ - Install all dependencies           │
├─────────────────────────────────────┤
│ Stage 2: builder                     │
│ - Copy dependencies                  │
│ - Build Vite application             │
├─────────────────────────────────────┤
│ Stage 3: runner (production)         │
│ - Minimal Alpine Linux               │
│ - Non-root user                      │
│ - Production dependencies            │
│ - Security hardening                 │
└─────────────────────────────────────┘

Volume Architecture

Container Volumes:
├── /app/data         → Persistent database storage
├── /app/uploads      → User uploaded files
├── /app/docs         → Documentation (bind mount)
├── /app/node_modules → NPM packages (named volume)
├── /app/.tmp         → Temporary files
└── /home/nodejs/.claude → Claude CLI config

Security Implementation

1. Build-Time Security

  • Multi-stage builds to minimize attack surface
  • Only production dependencies in final image
  • No build tools in production (except for npm capability)
  • Specific package versions locked

2. Runtime Security

  • Non-root user: nodejs (UID 1001)
  • Capability drops: All except essential (CHOWN, SETUID, SETGID, DAC_OVERRIDE)
  • No new privileges: Prevents privilege escalation
  • Security headers: Helmet.js enabled
  • Rate limiting: 100 requests per 15 minutes
  • Health checks: Every 30 seconds

3. File Permissions

/app              → 755 (standard)
/app/docs/*       → 666 (writable, non-executable)
/app/docs         → 777 (directory writable)
/app/node_modules → 777 (npm install capability)
/app/data         → 777 (database writable)
/app/uploads      → 777 (uploads writable)

Critical Dependencies

1. Native Node Modules

  • bcrypt: Password hashing (requires Python, GCC)
  • better-sqlite3: Database (requires Python, GCC, Make)
  • node-pty: Terminal emulation (requires Python, GCC)
  • sharp: Image processing (pre-built or requires build tools)

2. Claude CLI

  • Current Status: Placeholder in Dockerfile
  • Required Action: Implement proper installation method
  • Options:
    • Mount from host system
    • Download during build (requires auth)
    • Custom installation script

3. Build Tools (Included for npm capability)

  • Python3
  • GCC/G++
  • Make
  • Git (for git-based npm packages)

Environment Variables

Required for Production

SESSION_SECRET      # JWT session secret (generate strong random)
JWT_SECRET          # JWT token secret (generate strong random)

Optional Configuration

NODE_ENV           # production/development (default: production)
PORT               # Server port (default: 3005)
HOST               # Server host (default: 0.0.0.0)
DB_PATH            # Database path (default: /app/data/sasha.db)
DOCS_PATH          # Docs directory (default: /app/docs)
HELMET_ENABLED     # Enable Helmet.js (default: true)
RATE_LIMIT_ENABLED # Enable rate limiting (default: true)
RATE_LIMIT_MAX     # Max requests (default: 100)
RATE_LIMIT_WINDOW_MS # Time window (default: 900000)
MAX_FILE_SIZE      # Max upload size (default: 52428800)
CLAUDE_HOME        # Claude config directory

Local Testing Workflow

1. Build the Image

# Production build
./scripts/docker-build.sh production

# Development build (when Dockerfile.dev exists)
./scripts/docker-build.sh development

2. Run Tests

# Automated test suite
./scripts/docker-test.sh

# Tests performed:
# - Health endpoint check
# - Static file serving
# - Docs directory writability
# - Non-root user verification
# - npm package accessibility
# - Environment variable validation

3. Start Container

# Using docker-compose (recommended)
docker-compose up

# Or with environment file
docker-compose --env-file .env.production up

# Development mode (when configured)
docker-compose --profile dev up

4. Install Additional Packages

# Install packages in running container
./scripts/npm-install-docker.sh axios lodash

# Packages are installed and package.json is updated
# Remember to rebuild image to persist changes

5. Access Application

Next Steps Implementation

Phase 1: Complete Local Docker Setup (Current)

  • Create Dockerfile
  • Create docker-compose.yml
  • Create build scripts
  • Update server for environment variables
  • Add /api/health endpoint
  • Test container locally
  • Verify all functionality works

Phase 2: Development Environment

  • Create Dockerfile.dev with hot-reload
  • Configure development volumes
  • Set up development environment variables
  • Test development workflow

Phase 3: Claude CLI Integration

  • Research Claude CLI installation methods
  • Implement installation in Dockerfile
  • Test Claude CLI functionality
  • Configure Claude settings

Phase 4: Production Hardening

  • Implement secrets management
  • Add monitoring and logging
  • Configure backup strategies
  • Performance optimization
  • Security scanning

Phase 5: GCP Cloud Run Deployment

  • Create Cloud Build configuration
  • Set up Artifact Registry
  • Configure Cloud Run service
  • Set up Cloud SQL (if needed)
  • Configure Cloud Storage for uploads
  • Set up Cloud Load Balancer
  • Implement CI/CD pipeline

Testing Checklist

Container Functionality

  • Application starts successfully
  • Can log in and authenticate
  • WebSocket connections work
  • File uploads work
  • Docs directory is writable
  • Database persists between restarts
  • npm packages can be installed

Security Verification

  • Running as non-root user
  • Capabilities properly dropped
  • Rate limiting works
  • Security headers present
  • No sensitive data in logs
  • Secrets properly managed

Performance Testing

  • Container starts within 30 seconds
  • Health checks pass consistently
  • Memory usage stays within limits
  • CPU usage is reasonable
  • Response times are acceptable

Troubleshooting Guide

Common Issues

Container Won't Start

# Check logs
docker logs sasha-studio

# Check health status
docker inspect sasha-studio --format='{{json .State.Health}}'

# Verify environment variables
docker exec sasha-studio env | grep -E 'SESSION_SECRET|JWT_SECRET'

Permission Denied Errors

# Fix volume permissions
docker exec sasha-studio chown -R nodejs:nodejs /app/data
docker exec sasha-studio chmod 777 /app/docs

npm Install Fails

# Check node_modules volume
docker exec sasha-studio ls -la /app/node_modules

# Rebuild with fresh volume
docker-compose down -v
docker-compose up --build

Claude CLI Not Working

# Verify Claude installation
docker exec sasha-studio which claude

# Check Claude config
docker exec sasha-studio ls -la /home/nodejs/.claude

Success Metrics

Functionality

  • All features work in containerized environment
  • Data persists across container restarts
  • Can install and use new npm packages
  • Docs remain editable and accessible

Security

  • No root processes running
  • No unnecessary capabilities
  • Secrets not exposed in image
  • Rate limiting prevents abuse

Performance

  • Container size < 500MB
  • Startup time < 30 seconds
  • Memory usage < 512MB idle
  • Response time < 200ms for API calls

Maintainability

  • Easy to update dependencies
  • Clear build and deployment process
  • Comprehensive logging
  • Automated testing

Repository Structure

claudecodeui/
├── Dockerfile                 # Production multi-stage build
├── Dockerfile.dev            # Development build (pending)
├── docker-compose.yml        # Local orchestration
├── .dockerignore            # Build context optimization
├── scripts/
│   ├── docker-build.sh      # Build automation
│   ├── docker-test.sh       # Testing automation
│   └── npm-install-docker.sh # Package management
├── docs/
│   └── docker-deployment-plan.md # This document
└── server/
    └── index.js             # Needs env var updates

Conclusion

The Docker containerization of Sasha Studio is progressing well with security-first design, proper dependency management, and local testing capabilities. The next critical steps are completing the server environment variable integration and implementing proper Claude CLI installation before moving to GCP deployment.