OSIT-AE-App-Svelte/documentation/archive/PROJECT__AE_Docker_CI_BuildKit_implement.md

Project: AE Docker + CI BuildKit Implementation

Status: Proposed

Goal: Make Docker image builds for Aether cache-friendly using BuildKit/buildx and CI registry caching, while keeping local developer caches small and manageable.

Summary

• Implement a BuildKit-friendly multi-stage Dockerfile pattern for frontend and API images.
• Add CI buildx examples that push/read registry-based cache to avoid local disk bloat.
• Provide cache retention/rotation guidance and developer commands for safe pruning.

Scope

• Repository areas: aether_container_env/, root Dockerfile (if present), and CI pipeline definitions (Gitea/Drone or other).
• Non-goal: full CI pipeline migration to a new provider. This work provides CI snippets and a PR-ready set of files for your CI team.

Deliverables (this PR)

• documentation/PROJECT__AE_Docker_CI_BuildKit_implement.md (this file)
• aether_container_env/Dockerfile.buildkit.example — BuildKit-friendly multi-stage Dockerfile example.
• aether_container_env/ci_buildx_example.sh — standalone CI script examples (registry cache + local cache usage).
• documentation/AE_Docker_CI_cache_policy.md — cache rotation and prune guidance.

Tasks (implementation checklist)

• Review existing Dockerfile(s) under aether_container_env/ and repository root.
• Replace/extend Dockerfile with multi-stage BuildKit-friendly layout (use example as guide).
• Ensure .dockerignore (already added) excludes large build artifacts.
• Add CI step using docker buildx build with --cache-from and --cache-to pointed at a registry cache.
• Add a scheduled job or registry lifecycle rule to delete old cache images (30 days default).
• Document required CI secrets and permissions (registry write/read) for the operations team.
• Run verification builds (dev local with BuildKit; CI runs with cache) and record timings.

Verification

• Local dev: DOCKER_BUILDKIT=1 build with --cache-to/--cache-from shows cache hits on second run and faster build time.
• CI: subsequent CI runs log cache hit from buildx and total build time reduced vs baseline.
• Confirm registry contains cache image tags and that rotation job/prune removes old entries.

Notes about Gitea/CI

• Gitea does not include native Actions like GitHub; teams typically use Drone CI, Tekton, or a self-hosted runner that can execute the docker/buildx CLI.
• The provided ci_buildx_example.sh is intentionally provider-agnostic — pasteable into Drone, Jenkins, GitLab CI, or any shell-capable runner.

Risks & Mitigations

• Risk: Unbounded registry cache growth. Mitigation: enforce retention policy and rotation job; prefer a single cache tag reused by CI.
• Risk: Developers unfamiliar with BuildKit. Mitigation: examples show simple DOCKER_BUILDKIT=1 usage and local cache prune commands.

Next steps for the container team

1. Review examples in aether_container_env/ and adapt the Dockerfile to your runtime constraints (ssl certs, env injection, secrets).
2. Add a CI job using the ci_buildx_example.sh snippet; configure registry credentials as secrets.
3. Add a scheduled job to rotate/delete old cache images or configure registry lifecycle rules.
4. Run a before/after benchmark of time npm run build:prod inside the build stage to quantify improvement.

Files included in this PR for reference:

• aether_container_env/Dockerfile.buildkit.example
• aether_container_env/ci_buildx_example.sh
• documentation/AE_Docker_CI_cache_policy.md