Skip to content

Comments

build: migrate Dockerfile to distroless base#61

Merged
allisson merged 2 commits intomainfrom
update-agents
Feb 21, 2026
Merged

build: migrate Dockerfile to distroless base#61
allisson merged 2 commits intomainfrom
update-agents

Conversation

@allisson
Copy link
Owner

Replaced Alpine-based scratch image with Google Distroless (Debian 13 Trixie) for improved security posture and reduced attack surface. Implemented comprehensive multi-architecture build support (linux/amd64, linux/arm64) with cross-compilation via Docker buildx.

Key Security Enhancements:

  • Non-root user execution (UID 65532) - BREAKING CHANGE from v0.9.0 root user
  • SHA256 digest pinning for immutable base image (prevents supply chain attacks)
  • Read-only filesystem support with static binary (no runtime dependencies)
  • No shell, package manager, or system utilities (minimal attack surface)
  • Comprehensive OCI labels for SBOM generation and security scanning

Build System Improvements:

  • Build-time version injection via ldflags (VERSION, BUILD_DATE, COMMIT_SHA)
  • Multi-stage build with dependency layer caching optimization
  • BUILDPLATFORM/TARGETPLATFORM support for native cross-compilation
  • Explicit CGO_ENABLED=0 for fully static binary

Documentation Additions:

  • Inline Dockerfile comments explaining each stage and security decision
  • Health check documentation (HTTP probes vs HEALTHCHECK limitations)
  • Runtime security notes for production deployments
  • Usage examples for different commands (server, migrate, create-kek)

Breaking Change: Volume permissions may require adjustment when upgrading from v0.9.0 due to non-root user switch. See docs/operations/troubleshooting/volume-permissions.md for migration guide.

Replaced Alpine-based scratch image with Google Distroless (Debian 13 Trixie) for improved security posture and reduced attack surface. Implemented comprehensive multi-architecture build support (linux/amd64, linux/arm64) with cross-compilation via Docker buildx.

Key Security Enhancements:
- Non-root user execution (UID 65532) - BREAKING CHANGE from v0.9.0 root user
- SHA256 digest pinning for immutable base image (prevents supply chain attacks)
- Read-only filesystem support with static binary (no runtime dependencies)
- No shell, package manager, or system utilities (minimal attack surface)
- Comprehensive OCI labels for SBOM generation and security scanning

Build System Improvements:
- Build-time version injection via ldflags (VERSION, BUILD_DATE, COMMIT_SHA)
- Multi-stage build with dependency layer caching optimization
- BUILDPLATFORM/TARGETPLATFORM support for native cross-compilation
- Explicit CGO_ENABLED=0 for fully static binary

Documentation Additions:
- Inline Dockerfile comments explaining each stage and security decision
- Health check documentation (HTTP probes vs HEALTHCHECK limitations)
- Runtime security notes for production deployments
- Usage examples for different commands (server, migrate, create-kek)

Breaking Change: Volume permissions may require adjustment when upgrading from v0.9.0 due to non-root user switch. See docs/operations/troubleshooting/volume-permissions.md for migration guide.
@allisson allisson merged commit 66597f7 into main Feb 21, 2026
2 checks passed
@allisson allisson deleted the update-agents branch February 21, 2026 16:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant