DR-007: Container-Based Tooling Infrastructure

Status

[x] Accepted
[ ] Proposed
[ ] Rejected
[ ] Deprecated
[ ] Superseded

Date: 2024-11-20

Context

Documentation builds, diagram processing, security scanning require reproducible environments, tool version pinning, and cross-platform support (Windows/Linux/macOS).

Problem: How to ensure consistent builds across local development and CI environments?

Decision

Docker containers as primary execution environment for documentation, diagrams, and security tooling.

Container Modules:

mkdocs-pdf - Chromium + Playwright + MkDocs (PDF generation)
mkdocs-site - MkDocs + plugins (HTML site)
mermaid-cli - Mermaid diagram rendering
drawio-cli - Draw.io diagram processing (Python)
pdf-tools - PDF manipulation utilities
static-site - Nginx static serving
ext-eac - Multi-arch Docker extension (linux/amd64, linux/arm64)

Build Configuration:

Multi-platform builds via buildx
Registry caching (GitHub Container Registry)
SBOM and provenance generation
Pushed to ghcr.io/ready-to-release/*

Container Component Type:

dockerfile:
  builder: buildx
  scanners: [sbom, vuln, secrets, iac]
  requirements: [docker]

Consequences

Positive: Reproducible builds, tool isolation, multi-platform support, fast CI (cached layers), no host dependencies, version pinning

Negative: Docker required, container overhead, image maintenance, registry storage costs

Alternatives Considered

Local Tool Installation: Rejected - version drift, platform inconsistencies, dependency conflicts
VM-Based Builds: Rejected - slow startup, resource heavy, complex configuration
Nix/Guix: Rejected - learning curve, limited Windows support, unfamiliar ecosystem

Tutorials | How-to Guides | Explanation | Reference

You are here: Reference — information-oriented technical descriptions of the system.