Skip to main content

POD Requirements Analysis - Production-Ready Persistent Pods

Date: 2025-10-26 Source: archive/claude-code-initial-setup/ submodule analysis Status: Ready for Dockerfile integration

📦 Debian Libraries Required​

TIER 1: Essential Build Tools (Required)​

apt-get install -y \
    build-essential \      # gcc, g++, make for compiling
    jq \                   # JSON processor for scripts
    wget \                 # HTTP downloads
    tree \                 # Directory visualization
    htop \                 # Process monitor
    vim \                  # Text editor
    nano                   # Alternative editor

TIER 2: Development Enhancements (Required)​

apt-get install -y \
    git-lfs \              # Git Large File Storage
    ripgrep \              # Fast code search (rg command)
    fzf \                  # Fuzzy finder
    tmux \                 # terminal multiplexer
    rsync \                # File synchronization
    zip \                  # Archive creation
    unzip \                # Archive extraction
    silversearcher-ag      # Code search tool (ag command)

TIER 3: Python Development (Conditional - if Python needed)​

apt-get install -y \
    python3 \              # Python 3 interpreter
    python3-pip \          # Python package manager
    python3-venv \         # Virtual environments
    python3-dev \          # Development headers
    pylint \               # Python linter
    black                  # Python formatter

TIER 4: Network & Debugging Tools (Optional - for troubleshooting)​

apt-get install -y \
    netcat-openbsd \       # Network debugging
    telnet \               # Remote access
    nmap \                 # Network scanner
    traceroute \           # Route tracing
    dnsutils \             # DNS tools (dig, nslookup)
    net-tools \            # Network configuration (ifconfig, netstat)
    iputils-ping           # Ping utility

Playwright System Dependencies (if theia uses browser testing)​

npx playwright install-deps
# Installs: chromium, firefox, webkit browsers + system libraries

🔧 Node.js Global Packages​

TypeScript & JavaScript Tools​

npm install -g \
    typescript \           # TypeScript compiler
    ts-node \              # TypeScript execution
    @types/node \          # Node.js type definitions
    eslint \               # JavaScript/TypeScript linter
    prettier               # Code formatter

Build Tools​

npm install -g \
    vite \                 # Frontend build tool (already in package.json)
    esbuild \              # Fast bundler
    webpack \              # Module bundler
    webpack-cli            # Webpack CLI

Package Managers (Alternative)​

npm install -g \
    pnpm \                 # Fast package manager
    yarn                   # Alternative package manager

AI Tools​

npm install -g \
    @google/gemini-cli     # Google Gemini CLI (multi-llm support)

Development Utilities​

npm install -g \
    http-server \          # Quick HTTP server
    nodemon \              # Auto-restart on changes
    concurrently \         # Run multiple commands
    react-devtools \       # React debugging
    create-react-app \     # React project scaffolding
    create-next-app        # Next.js scaffolding

Playwright (Browser Testing)​

npm install -g playwright
npx playwright install     # Install browsers

🦀 Rust Components​

1. V5 Backend API Server​

Location: /home/hal/v4/PROJECTS/t2/backend/target/release/api-server Binary Name: coditect-v5-api Version: 0.1.0 Purpose: V5 Rust backend (Actix-web + FoundationDB) Build Command: cargo build --release from backend/ directory

Dependencies:

  • actix-web 4.4 (web framework)
  • tokio 1.35 (async runtime)
  • foundationdb 0.9 (database)
  • jsonwebtoken 9.1 (JWT auth)
  • argon2 0.5 (password hashing)

2. Codi2 Monitoring & Audit System​

Location: /home/hal/v4/PROJECTS/t2/archive/coditect-v4/codi2/ Binary Name: codi2 Version: 0.2.0 Purpose: Race-free monitoring and coordination for multi-agent development Build Command: cargo build --release from archive/coditect-v4/codi2/ directory

Features:

  • FoundationDB-backed audit logging
  • Real-time file system monitoring (FSEvents)
  • Multi-agent coordination and session tracking
  • Complete build lifecycle management with UUID tracking
  • WebSocket server for real-time communication (port 8765)
  • MCP server for AI tool integration

Key Capabilities:

# Functional areas
✓ Audit Logger - Event tracking to FDB
✓ File Monitor - FSEvents without race conditions
✓ Message Bus - tokio channel communication
✓ State Store - dashmap concurrency
✓ CLI Commands - User interface
✓ Session Management - Multi-agent coordination
✓ Export Management - Data archival

3. File Monitor Service​

Location: /home/hal/v4/PROJECTS/t2/src/file-monitor/ Binary Name: monitor (example binary: target/release/examples/monitor) Version: 0.1.0 Purpose: File system monitoring for audit logging Build Command: cargo build --release --examples from src/file-monitor/ directory

Features:

  • Real-time file system event detection
  • SHA256 checksum generation
  • JSON event logging
  • Prometheus metrics export
  • macOS FSEvent support

Rust Binary Integration Strategy​

Multi-stage Dockerfile:

# Stage 1: Build V5 Backend
FROM rust:1.75-slim AS v5-backend-builder
WORKDIR /build
RUN apt-get update && apt-get install -y build-essential libssl-dev pkg-config
COPY backend/ ./backend/
WORKDIR /build/backend
RUN cargo build --release
# Binary at: /build/backend/target/release/api-server

# Stage 2: Build Codi2 (from V4 archive)
FROM rust:1.75-slim AS codi2-builder
WORKDIR /build
RUN apt-get update && apt-get install -y build-essential libssl-dev pkg-config
COPY archive/coditect-v4/codi2/ ./codi2/
WORKDIR /build/codi2
RUN cargo build --release --all-features
# Binary at: /build/codi2/target/release/codi2

# Stage 3: Build File Monitor
FROM rust:1.75-slim AS monitor-builder
WORKDIR /build
RUN apt-get update && apt-get install -y build-essential
COPY src/file-monitor/ ./file-monitor/
WORKDIR /build/file-monitor
RUN cargo build --release --examples
# Binary at: /build/file-monitor/target/release/examples/monitor

# Stage 4: Runtime Image
FROM node:20-slim
WORKDIR /app

# Install runtime dependencies
RUN apt-get update && apt-get install -y \
    build-essential jq wget tree htop vim nano \
    git-lfs ripgrep fzf tmux rsync zip unzip \
    nginx curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Copy all Rust binaries
COPY --from=v5-backend-builder /build/backend/target/release/api-server /usr/local/bin/coditect-v5-api
COPY --from=codi2-builder /build/codi2/target/release/codi2 /usr/local/bin/codi2
COPY --from=monitor-builder /build/file-monitor/target/release/examples/monitor /usr/local/bin/file-monitor

# Make all binaries executable
RUN chmod +x /usr/local/bin/coditect-v5-api /usr/local/bin/codi2 /usr/local/bin/file-monitor

# Verify binaries
RUN coditect-v5-api --version || echo "V5 API binary ready" && \
    codi2 --version && \
    file-monitor --help || echo "File monitor binary ready"

Rust Cargo Tools (Optional - for development pods)​

cargo install \
    cargo-watch \          # Auto-recompile on changes
    cargo-edit \           # Manage dependencies (cargo add, cargo rm)
    cargo-outdated \       # Check outdated dependencies
    ripgrep \              # Code search (rg)
    bat \                  # Cat alternative with syntax highlighting
    exa                    # Ls alternative

📁 .coditect Configuration Requirements​

Directory Structure to Include​

.coditect/
├── logs/                  # Runtime logs directory
│   └── events.log         # File monitor events (JSON format)
├── settings.json          # Runtime settings (from claude-code-initial-setup)
├── agents/                # Agent definitions (copy from archive)
├── skills/                # Skill definitions (copy from archive)
├── scripts/               # Runtime scripts (copy from archive)
└── workflows/             # Workflow templates (copy from archive)

Critical Files from claude-code-initial-setup​

1. Settings File (archive/claude-code-initial-setup/.claude/settings.json):

{
  "autoApprove": {
    "patterns": ["git commit*", "npm run type-check*", "mv*", "git mv*", "git add*"]
  },
  "hooks": {
    "PostToolUse": [...]
  }
}

2. Agents (copy entire .claude/agents/ directory):

  • code-reviewer.md
  • test-writer.md
  • doc-generator.md
  • file-organizer.md
  • prior-session-agent.md

3. Skills (copy entire .claude/skills/ directory):

  • session-aware/
  • project-tracker/
  • example-skill/

4. Workflows (copy entire .claude/workflows/ directory):

  • code-review-workflow.md
  • testing-workflow.md
  • cicd-workflow.md

5. Scripts (copy entire .claude/scripts/ directory):

  • install-dev-environment.sh
  • install-modern-dev-stack.sh
  • install-userspace-tools.sh
  • test-hooks.sh

🗂️ Archive References to Include​

V4 Database Models (for FDB schema reference)​

Location: archive/coditect-v4/docs/reference/database-models/ Purpose: Reference for FoundationDB schema design (19 models) Include in Docker: NO - Reference only, not runtime requirement

Multi-llm Integration Analysis (for LM Studio reference)​

Location: docs/analysis-human-layer/ Purpose: Multi-llm architecture patterns, LM Studio integration Include in Docker: NO - Documentation only

🚀 Dockerfile Integration Strategy​

Multi-Stage Build Layers​

Stage 1: Frontend Build (already exists)

FROM node:20-slim AS frontend-builder
WORKDIR /build
COPY package*.json ./
RUN npm install --legacy-peer-deps
COPY src/ ./src/
RUN npx vite build

Stage 2: theia Build with Icons + Branding (fixed in dockerfile.combined-fixed)

FROM node:20-slim AS theia-builder
WORKDIR /build
# Install system deps
RUN apt-get update && apt-get install -y \
    python3 make g++ git curl
# Copy from correct directory (theia-app/, not .theia/)
COPY theia-app/package*.json ./
RUN npm install --legacy-peer-deps
COPY theia-app/src ./src
COPY theia-app/lib ./lib          # ← Custom branding
COPY theia-app/plugins ./plugins  # ← Icon themes
RUN npx theia build

Stage 3: Rust Backend Build (NEW)

FROM rust:1.75-slim AS rust-builder
WORKDIR /build
# Install system deps for FDB
RUN apt-get update && apt-get install -y \
    build-essential libssl-dev pkg-config
# Copy backend source
COPY backend/ ./backend/
WORKDIR /build/backend
RUN cargo build --release
# Binary at: /build/backend/target/release/api-server

Stage 4: Runtime Image with ALL Components (UPDATED)

FROM node:20-slim
WORKDIR /app

# Install TIER 1 + TIER 2 Debian packages (essential)
RUN apt-get update && apt-get install -y \
    build-essential jq wget tree htop vim nano \
    git-lfs ripgrep fzf tmux rsync zip unzip silversearcher-ag \
    nginx curl ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Install TIER 3 Python (conditional - if needed for scripts)
RUN apt-get update && apt-get install -y \
    python3 python3-pip python3-venv python3-dev \
    && rm -rf /var/lib/apt/lists/*

# Copy V5 Frontend build
COPY --from=frontend-builder /build/dist /app/v5-frontend

# Copy theia build (with icons + branding)
COPY --from=theia-builder /build /app/theia

# Copy Rust backend binary
COPY --from=rust-builder /build/backend/target/release/api-server /usr/local/bin/coditect-v5-api
RUN chmod +x /usr/local/bin/coditect-v5-api

# Copy .coditect configs (from claude-code-initial-setup)
COPY archive/claude-code-initial-setup/.claude /app/.coditect
RUN mkdir -p /app/.coditect/logs

# Install Node.js global packages
RUN npm install -g \
    typescript ts-node eslint prettier \
    vite esbuild webpack webpack-cli \
    http-server nodemon concurrently \
    @google/gemini-cli

# Copy NGINX config
COPY nginx-combined.conf /etc/nginx/sites-available/default

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=60s --retries=3 \
    CMD curl -f http://localhost/health || exit 1

# Start script
COPY start-combined.sh /app/start.sh
RUN chmod +x /app/start.sh

EXPOSE 80

CMD ["/app/start.sh"]

📊 Cloud Build Optimization​

Current Issue​

Problem: Build failing due to insufficient memory/CPU, too many layers

Solution: Optimized Cloud Build Configuration​

File: cloudbuild-combined.yaml

steps:
  # Step 1: Build Docker image with proper caching and layer optimization
  - name: 'gcr.io/cloud-builders/docker'
    id: 'build-image'
    args:
      - 'build'
      - '--cache-from=us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:latest'
      - '--build-arg=BUILDKIT_INLINE_CACHE=1'  # Enable cache export
      - '-t'
      - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:$BUILD_ID'
      - '-t'
      - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:latest'
      - '-f'
      - 'dockerfile.combined-fixed'
      - '.'
    timeout: '3600s'  # 1 hour for full build

  # Step 2: Push BUILD_ID tag
  - name: 'gcr.io/cloud-builders/docker'
    id: 'push-build-id'
    args:
      - 'push'
      - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:$BUILD_ID'
    waitFor: ['build-image']

  # Step 3: Push latest tag
  - name: 'gcr.io/cloud-builders/docker'
    id: 'push-latest'
    args:
      - 'push'
      - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:latest'
    waitFor: ['build-image']

  # Step 4: Deploy to GKE StatefulSet
  - name: 'gcr.io/cloud-builders/kubectl'
    id: 'deploy-gke'
    args:
      - 'set'
      - 'image'
      - 'statefulset/coditect-combined'
      - 'combined=us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:$BUILD_ID'
      - '--namespace=coditect-app'
    env:
      - 'CLOUDSDK_COMPUTE_ZONE=us-central1-a'
      - 'CLOUDSDK_CONTAINER_CLUSTER=codi-poc-e2-cluster'
    waitFor: ['push-build-id', 'push-latest']

# Build timeout (increased from 1800s to 3600s)
timeout: '3600s'

# Machine type - CRITICAL for build success
options:
  machineType: 'E2_HIGHCPU_32'  # 32 CPUs (proven successful from Oct 13 build)
  diskSizeGb: 100               # 100GB disk
  logging: CLOUD_LOGGING_ONLY
  env:
    - 'NODE_OPTIONS=--max_old_space_size=8192'  # 8GB heap for Node.js
    - 'DOCKER_BUILDKIT=1'                       # Enable BuildKit for better caching

# Images to push
images:
  - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:$BUILD_ID'
  - 'us-central1-docker.pkg.dev/${PROJECT_ID}/coditect/coditect-combined:latest'

Layer Optimization Strategy​

Problem: Too many layers cause build failures

Solution: Combine RUN statements strategically

BEFORE (BAD - 10+ layers):

RUN apt-get update
RUN apt-get install -y build-essential
RUN apt-get install -y jq
RUN apt-get install -y wget
RUN apt-get install -y tree
...

AFTER (GOOD - 1 layer):

RUN apt-get update && apt-get install -y \
    build-essential jq wget tree htop vim nano \
    git-lfs ripgrep fzf tmux rsync zip unzip \
    && rm -rf /var/lib/apt/lists/*

Layer Breakdown (Optimized):

  1. Frontend build stage: ~15 layers (cacheable)
  2. theia build stage: ~18 layers (cacheable)
  3. Rust build stage: ~12 layers (cacheable)
  4. Runtime stage: ~25 layers total
    • Base image: 5 layers
    • System packages: 2 layers (TIER 1+2 combined, TIER 3 separate)
    • COPY operations: 4 layers (frontend, theia, backend, .coditect)
    • NPM global: 1 layer
    • Config/scripts: 3 layers

Total: ~70 layers (within Docker's 127 layer limit)

🔍 Gap Analysis: Current vs. Production-Ready​

Current State (Build #12)​

✅ Frontend build working (React + Vite) ✅ theia icons fixed (vs-seti + vscode-icons) ✅ Custom Coditect branding preserved ✅ NGINX routing configured ✅ V5 Rust backend built and deployed separately ❌ .coditect configs NOT in Docker image ❌ Development tools NOT installed in pods ❌ Rust backend NOT bundled with frontend+theia ❌ Cloud Build using suboptimal machine type (8 CPUs, not 32)

Production-Ready State (This Document)​

✅ All TIER 1 + TIER 2 Debian packages included ✅ .coditect directory with agents, skills, workflows ✅ Rust backend binary bundled in same image ✅ Node.js global tools pre-installed ✅ Optimized multi-stage build with layer combining ✅ E2_HIGHCPU_32 machine type (32 CPUs) ✅ Docker BuildKit caching enabled ✅ Increased timeout to 3600s (1 hour)

📋 Implementation Checklist​

Phase 1: Dockerfile Updates​

  • Update dockerfile.combined-fixed to include Rust build stage
  • Add Debian package installation (TIER 1 + TIER 2)
  • Copy .coditect configs from archive/claude-code-initial-setup/.claude/
  • Install Node.js global packages
  • Combine RUN statements to reduce layers
  • Add Rust backend binary to /usr/local/bin/coditect-v5-api

Phase 2: Cloud Build Updates​

  • Update cloudbuild-combined.yaml machine type to E2_HIGHCPU_32
  • Increase timeout to 3600s
  • Enable Docker BuildKit (DOCKER_BUILDKIT=1)
  • Add --cache-from to reuse previous builds
  • Set NODE_OPTIONS=--max_old_space_size=8192

Phase 3: Start Script Updates​

  • Update start-combined.sh to start Rust backend alongside NGINX + Node
  • Add health check endpoint validation
  • Add .coditect logs initialization

Phase 4: Testing​

  • Build locally with docker build -f dockerfile.combined-fixed -t coditect-combined:prod-ready .
  • Test container startup and health checks
  • Verify all binaries are present (coditect-v5-api, rg, jq, tree, etc.)
  • Verify .coditect configs are accessible
  • Run Cloud Build and deploy to GKE

Phase 5: Deployment​

  • Trigger Cloud Build: gcloud builds submit --config cloudbuild-combined.yaml .
  • Verify build completes (should take 30-40 min with E2_HIGHCPU_32)
  • Deploy to GKE StatefulSet
  • Verify pods are Running (3/3 or 10/10 with Starter config)
  • Test at https://coditect.ai/theia and https://api.coditect.ai

🎯 Expected Outcomes​

Build Time: 30-40 minutes (down from 60+ min with 8 CPUs) Image Size: ~4.5 GB (up from ~3.5 GB due to dev tools) Layer Count: ~70 layers (within 127 limit) Memory Usage (Build): ~7-8 GB Node heap, 10-12 GB total CPU Usage (Build): 28-30 CPUs utilized (out of 32)

Runtime Benefits:

  • ✅ All development tools pre-installed in pods
  • ✅ No need to apt-get install during runtime
  • ✅ Claude Code agents/skills/workflows ready to use
  • ✅ Rust backend co-located with frontend/theia
  • ✅ Faster pod startup (no package installation)
  • ✅ Consistent environment across all pods

Status: ✅ Ready for Implementation Next Step: Update dockerfile.combined-fixed with Rust build stage and .coditect configs ETA: 2-3 hours (Dockerfile updates + Cloud Build + Deployment)