motovaultpro/PHASE-06-Docker-Modern.md

# PHASE-06: Docker Infrastructure Modernization

**Status**: 🔄 IN PROGRESS (Started 2025-08-24)  
**Duration**: 2 days  
**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**
  ```bash
  # 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**
  ```bash
  # 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**
  ```bash
  git add -A
  git commit -m "Docker baseline before modernization"
  git tag docker-baseline
  ```

### Step 2: Backend Multi-Stage Dockerfile
- [ ] **Create Optimized Backend Dockerfile**
  ```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**
  ```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**
  ```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**
  ```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**
  ```nginx
  # 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**
  ```bash
  # 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**
  ```yaml
  # 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**
  ```bash
  # 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**
  ```dockerfile
  # 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**
  ```bash
  # 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**
  ```bash
  # 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**  
  ```bash
  # Build production images
  docker build -f backend/Dockerfile -t mvp-backend-prod backend/
  docker build -f frontend/Dockerfile -t mvp-frontend-prod frontend/
  
  # Check image sizes
  docker images | grep mvp
  # Should be significantly smaller
  ```

- [ ] **Security Verification**
  ```bash
  # 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-prod
  ```

## ✅ 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# Full system test
make dev
curl http://localhost:3001/health
curl http://localhost:3000
# All functionality should work identically
```

## 🚨 Troubleshooting Guide

### Permission Issues
```bash
# 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
```bash
# 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
```bash
# 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-dev
```

## 🔄 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)
```bash
# 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
```bash
# 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)