From a9de12cee1e8f7081287fd2ef12344eba1230142 Mon Sep 17 00:00:00 2001 From: Gabriel Radureau Date: Tue, 7 Apr 2026 11:56:20 +0200 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D=20docs:=20enhance=20ADR=200020=20w?= =?UTF-8?q?ith=20comprehensive=20Docker=20build=20strategy=20documentation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- adr/0020-docker-build-strategy.md | 118 ++++++++++++++++++++++++++++++ 1 file changed, 118 insertions(+) diff --git a/adr/0020-docker-build-strategy.md b/adr/0020-docker-build-strategy.md index c7cedb5..c1d5061 100644 --- a/adr/0020-docker-build-strategy.md +++ b/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 \ No newline at end of file