motovaultpro/docs/changes/framework-updates/PHASE-06-Docker-Modern.md

PHASE-06: Docker Infrastructure Modernization

Status: ✅ COMPLETED (2025-08-24)
Duration: 1 hour
Prerequisites: TypeScript modernization complete (Phase 5) ✅
Next Phase: PHASE-07-Vehicles-Fastify

🎯 Phase Objectives

• Implement multi-stage Docker builds for smaller images
• Add non-root user containers for security
• Optimize Docker layers for better caching
• Reduce image sizes by 40-60%
• Improve build performance and security
• Maintain Docker-first development philosophy

📋 Detailed Implementation Steps

Step 1: Prerequisites & Current Analysis

• Verify Phase 5 Complete

  # Check TypeScript 5.4+ working
  make shell-backend && npx tsc --version && exit
  make shell-frontend && npx tsc --version && exit
  # Should both show 5.4+
  

• Analyze Current Docker Setup

  # Check current image sizes
  docker images | grep mvp
  # Document current sizes
  
  # Check current build times
  time make rebuild
  # Document baseline build time
  

• Create Docker Baseline

  git add -A
  git commit -m "Docker baseline before modernization"
  git tag docker-baseline
  

Step 2: Backend Multi-Stage Dockerfile

• Create Optimized Backend Dockerfile

  # backend/Dockerfile (new production version)
  # Stage 1: Base with dependencies
  FROM node:20-alpine AS base
  RUN apk add --no-cache dumb-init
  WORKDIR /app
  COPY package*.json ./
  
  # Stage 2: Development dependencies
  FROM base AS dev-deps
  RUN npm ci --include=dev
  
  # Stage 3: Production dependencies
  FROM base AS prod-deps
  RUN npm ci --omit=dev && npm cache clean --force
  
  # Stage 4: Build stage
  FROM dev-deps AS build
  COPY . .
  RUN npm run build
  
  # Stage 5: Production stage
  FROM base AS production
  RUN addgroup -g 1001 -S nodejs
  RUN adduser -S nodejs -u 1001
  COPY --from=prod-deps /app/node_modules ./node_modules
  COPY --from=build /app/dist ./dist
  COPY --from=build /app/package*.json ./
  USER nodejs
  EXPOSE 3001
  ENTRYPOINT ["dumb-init", "--"]
  CMD ["node", "dist/index.js"]
  

• Update Backend Development Dockerfile

  # backend/Dockerfile.dev (optimized development)
  FROM node:20-alpine AS base
  RUN apk add --no-cache git dumb-init
  WORKDIR /app
  
  # Install dependencies first for better caching
  COPY package*.json ./
  RUN npm ci
  
  # Add non-root user for development
  RUN addgroup -g 1001 -S nodejs
  RUN adduser -S nodejs -u 1001
  RUN chown -R nodejs:nodejs /app
  USER nodejs
  
  # Copy source (this layer changes frequently)
  COPY --chown=nodejs:nodejs . .
  
  EXPOSE 3001
  ENTRYPOINT ["dumb-init", "--"]
  CMD ["npm", "run", "dev"]
  

Step 3: Frontend Multi-Stage Dockerfile

• Create Optimized Frontend Dockerfile

  # frontend/Dockerfile (new production version)
  # Stage 1: Base with dependencies
  FROM node:20-alpine AS base
  RUN apk add --no-cache dumb-init
  WORKDIR /app
  COPY package*.json ./
  
  # Stage 2: Dependencies
  FROM base AS deps
  RUN npm ci && npm cache clean --force
  
  # Stage 3: Build stage
  FROM deps AS build
  COPY . .
  RUN npm run build
  
  # Stage 4: Production stage with nginx
  FROM nginx:alpine AS production
  RUN addgroup -g 1001 -S nodejs
  RUN adduser -S nodejs -u 1001
  COPY --from=build /app/dist /usr/share/nginx/html
  COPY nginx.conf /etc/nginx/nginx.conf
  USER nodejs
  EXPOSE 3000
  CMD ["nginx", "-g", "daemon off;"]
  

• Update Frontend Development Dockerfile

  # frontend/Dockerfile.dev (optimized development)
  FROM node:20-alpine AS base
  RUN apk add --no-cache git dumb-init
  WORKDIR /app
  
  # Install dependencies first for better caching
  COPY package*.json ./
  RUN npm ci
  
  # Add non-root user for development
  RUN addgroup -g 1001 -S nodejs
  RUN adduser -S nodejs -u 1001
  RUN chown -R nodejs:nodejs /app
  USER nodejs
  
  # Copy source (this layer changes frequently)
  COPY --chown=nodejs:nodejs . .
  
  EXPOSE 3000
  ENTRYPOINT ["dumb-init", "--"]
  CMD ["npm", "run", "dev", "--", "--host", "0.0.0.0"]
  

Step 4: Add Required Configuration Files

• Create nginx.conf for Frontend

  # frontend/nginx.conf
  events {
      worker_connections 1024;
  }
  
  http {
      include /etc/nginx/mime.types;
      default_type application/octet-stream;
  
      server {
          listen 3000;
          root /usr/share/nginx/html;
          index index.html;
  
          location / {
              try_files $uri $uri/ /index.html;
          }
  
          # Gzip compression
          gzip on;
          gzip_types text/plain text/css application/json application/javascript;
      }
  }
  

• Create .dockerignore Files

  # backend/.dockerignore
  node_modules
  npm-debug.log
  .git
  .gitignore
  README.md
  .env
  .env.local
  coverage
  .nyc_output
  
  # frontend/.dockerignore  
  node_modules
  npm-debug.log
  .git
  .gitignore
  README.md
  .env
  .env.local
  dist
  coverage
  .nyc_output
  

Step 5: Update Docker Compose Configuration

• Optimize docker-compose.yml

  # Update docker-compose.yml for better caching and security
  services:
    backend:
      build:
        context: ./backend
        dockerfile: Dockerfile.dev
        cache_from:
          - node:20-alpine
      user: "1001:1001"  # Run as non-root
      # ... rest of config
  
    frontend:
      build:
        context: ./frontend  
        dockerfile: Dockerfile.dev
        cache_from:
          - node:20-alpine
      user: "1001:1001"  # Run as non-root
      # ... rest of config
  

• Add BuildKit Configuration

  # Create docker-compose.build.yml for production builds
  # Enable BuildKit for faster builds
  # Add cache mount configurations
  

Step 6: Security Hardening

• Non-Root User Implementation

  • Verify all containers run as non-root user (nodejs:1001)
  • Test file permissions work correctly
  • Verify volumes work with non-root user

• Security Best Practices

  # In all Dockerfiles:
  # - Use specific image tags (node:20-alpine, not node:latest)
  # - Use dumb-init for proper signal handling
  # - Run as non-root user
  # - Use least-privilege principles
  

Step 7: Build Performance Optimization

• Layer Caching Optimization

  • Dependencies installed before source copy
  • Separate stages for better cache utilization
  • Proper .dockerignore to reduce context size

• BuildKit Features

  # Enable BuildKit
  export DOCKER_BUILDKIT=1
  export COMPOSE_DOCKER_CLI_BUILD=1
  
  # Test improved build performance
  time make rebuild
  

Step 8: Testing & Verification

• Development Environment Testing

  # Clean build test
  make down
  docker system prune -a
  make dev
  
  # Verify all services start correctly
  # Verify non-root user works
  # Verify volumes work correctly
  # Test hot reloading still works
  

• Production Build Testing

  # Build images
  docker build -f backend/Dockerfile -t mvp-backend backend/
  docker build -f frontend/Dockerfile -t mvp-frontend frontend/
  
  # Check image sizes
  docker images | grep mvp
  # Should be significantly smaller
  

• Security Verification

  # Verify running as non-root
  docker exec mvp-backend whoami  # Should show 'nodejs'
  docker exec mvp-frontend whoami  # Should show 'nodejs'
  
  # Check for security issues
  docker run --rm -v /var/run/docker.sock:/var/run/docker.sock \
    -v $(pwd):/app aquasec/trivy image mvp-backend
  

✅ Phase Completion Criteria

All checkboxes must be completed:

• Multi-stage Dockerfiles implemented for both services
• Non-root user containers working correctly
• Image sizes reduced by 40-60%
• Build times improved or maintained
• Development hot-reloading still works
• All services start correctly with new containers
• Security hardening implemented
• Production builds work correctly
• Volume mounts work with non-root users
• No functionality regressions

🧪 Testing Commands

Image Size Comparison

# Before modernization
docker images | grep mvp | head -n 2

# After modernization  
docker images | grep mvp | head -n 2
# Should show 40-60% size reduction

Build Performance Testing

# Clean build time
make down
docker system prune -a
time make rebuild

# Incremental build time (change a file)
touch backend/src/index.ts
time make rebuild
# Should be much faster due to layer caching

Security Testing

# User verification
make dev
docker exec mvp-backend id
docker exec mvp-frontend id
# Should show uid=1001(nodejs) gid=1001(nodejs)

# File permissions
docker exec mvp-backend ls -la /app
# Should show nodejs ownership

Functionality Testing

# Full system test
make dev
curl http://localhost:3001/health
curl http://localhost:3000
# All functionality should work identically

🚨 Troubleshooting Guide

Permission Issues

# If file permission errors:
# 1. Check volume mount permissions
# 2. Verify non-root user has access
# 3. May need to adjust host file permissions

# Fix volume permissions:
sudo chown -R 1001:1001 ./backend/src
sudo chown -R 1001:1001 ./frontend/src

Build Failures

# If multi-stage build fails:
# 1. Check each stage individually
# 2. Verify base image compatibility
# 3. Check file copy paths

# Debug specific stage:
docker build --target=build -f backend/Dockerfile backend/

Runtime Issues

# If containers don't start:
# 1. Check user permissions
# 2. Verify entry point scripts
# 3. Check file ownership

# Debug container:
docker run -it --entrypoint /bin/sh mvp-backend

🔄 Rollback Plan

If Docker changes cause issues:

1. Follow ROLLBACK-PROCEDURES.md Phase 6 section
2. Restore Docker files: git checkout docker-baseline
3. Clean Docker: docker system prune -a
4. Rebuild: make rebuild
5. Test system: Verify original Docker setup works

🚀 Success Metrics

Expected Improvements

• Image Size: 40-60% reduction
• Build Performance: 20-40% faster incremental builds
• Security: Non-root containers, hardened images
• Cache Efficiency: Better layer reuse

Benchmarks (Target)

# Image sizes (approximate targets):
# Backend: 200MB → 80-120MB
# Frontend: 150MB → 50-80MB

# Build times:
# Clean build: Similar or 10-20% faster
# Incremental: 50-70% faster

🔗 Handoff Information

Handoff Prompt for Future Claude

Continue MotoVaultPro Phase 6 (Docker Modern). Check PHASE-06-Docker-Modern.md for steps. Implement multi-stage Dockerfiles, non-root users, optimize for security and performance. TypeScript 5.4 from Phase 5 should be complete. Maintain Docker-first development.

Prerequisites Verification

# Verify Phase 5 complete
make shell-backend && npx tsc --version && exit  # Should show 5.4+
make shell-frontend && npx tsc --version && exit  # Should show 5.4+
make dev  # Should work correctly

📝 Docker Modernization Benefits

Security Improvements

• Non-root user containers
• Smaller attack surface
• Security-hardened base images
• Proper signal handling with dumb-init

Performance Benefits

• Multi-stage builds reduce final image size
• Better layer caching improves build speed
• Optimized dependency management
• Reduced context size with .dockerignore

Maintenance Benefits

• Cleaner, more organized Dockerfiles
• Better separation of concerns
• Easier to understand and modify
• Production-ready configurations

---

Phase 6 Status: Pending Phase 5 completion
Key Benefits: Smaller images, better security, faster builds
Risk Level: Medium (infrastructure changes require careful testing)