Pre-React-19 backup - working React 18 state
- Phase 1 analysis complete with performance baseline - All phase documentation files created - Ready to begin Phase 2 (React 19 Foundation) - Baseline: 940KB bundle, 13.1ms API response, 735 req/sec 🤖 Generated with [Claude Code](https://claude.ai/code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Eric Gullickson
475
PHASE-06-Docker-Modern.md
Normal file
475
PHASE-06-Docker-Modern.md
Normal file
@@ -0,0 +1,475 @@
|
||||
# PHASE-06: Docker Infrastructure Modernization
|
||||
|
||||
**Status**: ⏹️ PENDING (Waiting for Phase 5)
|
||||
**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)
|
||||
Reference in New Issue
Block a user