📝 docs: enhance ADR 0020 with comprehensive Docker build strategy documentation

adr/0020-docker-build-strategy.md

@@ -187,6 +187,8 @@ ENTRYPOINT ["/app/dance-lessons-coach"]
 2. **Simplicity**: Easier to maintain and troubleshoot
 3. **Consistency**: Matches proven patterns from working projects
 4. **Faster feedback**: Quicker build times in practice
+5. **Clear Separation**: Better distinction between development and production builds
+6. **Optimized Production**: Smaller, more secure production images
 
 ## Rationale
 
@@ -194,6 +196,51 @@ ENTRYPOINT ["/app/dance-lessons-coach"]
 2. **Simple Dockerfile**: Our `Dockerfile.build` doesn't require Buildx-specific features
 3. **Proven Pattern**: Traditional approach works reliably in production (webapp project)
 4. **CI Stability**: Reliability is more important than advanced features for CI/CD
+5. **Build Strategy**: Two-stage build provides better separation of concerns
+6. **Maintenance**: Simpler approach is easier to maintain and debug
+
+## CI/CD Pipeline Optimization
+
+### Changes Made
+
+1. **Removed Buildx Setup**: Eliminated `docker/setup-buildx-action@v3` from CI/CD workflow
+2. **Removed Go Build Steps**: Removed `actions/setup-go@v4`, `go mod tidy`, and individual Go tool installations
+3. **Added Docker Cache Usage**: All build steps now use the pre-built Docker cache image
+4. **Updated Production Build**: Production Docker build now uses `Dockerfile.prod`
+
+### CI/CD Workflow Structure
+
+```yaml
+# CI Pipeline Job Structure
+jobs:
+  build-cache:
+    # Builds Docker cache image if needed
+    
+  ci-pipeline:
+    needs: build-cache
+    steps:
+      - name: Set up build environment
+        # Sets CACHE_IMAGE variable with proper tag
+        
+      - name: Generate Swagger Docs using Docker cache
+        # Uses: docker run ${{ env.CACHE_IMAGE }} sh -c "cd pkg/server && go generate"
+        
+      - name: Build all packages using Docker cache
+        # Uses: docker run ${{ env.CACHE_IMAGE }} sh -c "go build ./..."
+        
+      - name: Run tests with coverage using Docker cache
+        # Uses: docker run ${{ env.CACHE_IMAGE }} sh -c "go test ./..."
+        
+      - name: Build and push Docker image
+        # Uses: docker build -t dance-lessons-coach -f Dockerfile.prod .
+```
+
+### Key Improvements
+
+1. **Faster Execution**: No need to set up Go environment for each job
+2. **Consistent Environment**: All builds use the same Docker cache image
+3. **Reduced Complexity**: Simpler workflow with fewer steps
+4. **Better Error Handling**: Docker cache handles dependency management
 
 ## Future Considerations
 
@@ -242,21 +289,92 @@ This decision prioritizes CI/CD reliability and simplicity over advanced feature
 
 ## Success Metrics
 
+### CI/CD Pipeline Metrics
+
 1. **CI/CD reliability**: No TLS certificate failures
 2. **Build consistency**: Predictable build times
 3. **Maintenance**: Reduced complexity and debugging time
 4. **Compatibility**: Works across all target environments
 
+### Build Strategy Metrics
+
+1. **Cache hit rate**: Percentage of CI runs using existing cache
+2. **Build time reduction**: Comparison of build times with vs without cache
+3. **Image size**: Production image size vs development image size
+4. **CI execution time**: Total CI pipeline duration
+
+### Quality Metrics
+
+1. **Build reproducibility**: Consistent builds across different environments
+2. **Error rate**: Reduction in CI/CD failures
+3. **Recovery time**: Time to recover from cache misses
+4. **Resource utilization**: Memory and CPU usage during builds
+
+## Implementation Checklist
+
+- [x] Create `Dockerfile.prod` for production builds
+- [x] Update `Dockerfile.build` for build cache
+- [x] Keep `Dockerfile` for development use
+- [x] Remove Docker Buildx from CI/CD workflow
+- [x] Remove Go build steps from CI/CD workflow
+- [x] Add Docker cache usage to all build steps
+- [x] Update production Docker build to use `Dockerfile.prod`
+- [x] Update ADR 0020 with comprehensive documentation
+- [x] Test changes locally
+- [x] Push changes to trigger CI/CD workflow
+- [ ] Monitor workflow execution
+- [ ] Verify successful completion
+- [ ] Document results and metrics
+
+## Monitoring and Validation
+
+### Workflow Monitoring
+
+```bash
+# Monitor the workflow
+./scripts/gitea-client.sh monitor-workflow arcodange dance-lessons-coach 419 30
+
+# Check job status
+./scripts/gitea-client.sh job-status arcodange dance-lessons-coach 419
+
+# List workflow jobs
+./scripts/gitea-client.sh list-workflow-jobs arcodange dance-lessons-coach 419
+```
+
+### Validation Commands
+
+```bash
+# Verify CI/CD changes
+./scripts/verify-cicd-changes.sh
+
+# Test new CI/CD workflow
+./scripts/test-new-cicd.sh
+
+# Check Dockerfile syntax
+docker run --rm -i hadolint/hadolint < Dockerfile.prod
+```
+
+## Expected Outcomes
+
+1. **Successful workflow execution**: Workflow 419 completes without errors
+2. **Cache image created**: Build cache image pushed to registry
+3. **Production image built**: Final Docker image built using `Dockerfile.prod`
+4. **Faster CI execution**: Reduced build times compared to previous approach
+5. **No certificate errors**: No TLS certificate verification failures
+
 ## References
 
 - [Docker Buildx Documentation](https://docs.docker.com/buildx/working-with-buildx/)
 - [Docker Build Documentation](https://docs.docker.com/engine/reference/commandline/build/)
 - [GitHub Actions Docker Examples](https://github.com/actions/starter-workflows/tree/main/ci-and-cd)
 - [webapp CI/CD Pipeline](https://gitea.arcodange.fr/arcodange-org/webapp/src/branch/main/.gitea/workflows/dockerimage.yaml)
+- [Docker Multi-stage Builds](https://docs.docker.com/build/building/multi-stage/)
+- [Alpine Linux Docker Images](https://hub.docker.com/_/alpine)
 
 ---
 
 **Approved by**: @arcodange
 **Date**: 2026-04-07
+**Updated**: 2026-04-07
 **Supersedes**: None
 **Superseded by**: None