How wolfi-dev/os works
Project Type and Purpose
• This is an open-source, monorepo of YAML-based package manifests and CI pipelines that drive the Wolfi GNU/Linux distribution.
• Developers contribute “<package>.yaml” files and patches under each package folder; CI then builds minimal container images (via apko) and APK packages (via melange).
High-Level System Components
• GitHub Repository
• Contains all package definitions (*.yaml), patch directories, docs, scripts, pipeline definitions.
• Hosts .github/workflows for CI and .github/chainguard for policy-driven automation.
• CI/CD Orchestration
• GitHub Actions: triggers on push/PR, runs lint, tests, security scans.
• Chainguard STS Workflows (ci-*.sts.yaml): perform CVE scanning, SBOM generation, license checks, automated approvals.
• Build Engines
• Melange: consumes package YAML + patches → produces APK packages/artifacts.
• Apko: builds OCI-compatible container images (wolfi-base, wolfi-bootstrap, etc.) from package artifacts.
• Artifact Stores
• Wolfi Package Repository: an HTTP-served APK index at packages.wolfi.dev/os.
• Container Registry: Chainguard’s OCI registry (cgr.dev/chainguard/wolfi-base).
• Public Signing Keys: served alongside the repository.
• Local Development
• .devcontainer and .vscode configurations for standardized IDE experience.
• Makefile and top-level scripts drive local testing, linting, packaging.
Relationships & Data Flows
• Developer commits YAML → GitHub repo
→ GitHub Actions + Chainguard CI run validations (lint, tests, security scans)
→ On approval, Melange builds APKs → Push to Wolfi package index
→ Apko builds images from index → Push to OCI registry
• Downstream systems (users, Kubernetes clusters, CI for container images) pull from the package index or OCI registry.
Architectural Patterns & Principles
• Mono-repo organizing thousands of small package definitions.
• GitOps/Policy as Code: workflows and policies drive quality and security gating.
• Pipeline as Code: pipelines defined alongside code in pipelines/ and .github/.
• Separation of Concerns:
• Package metadata (YAML) vs. build logic (melange/apko) vs. CI policy (sts.yaml).
Technologies & Frameworks
• GitHub Actions, Chainguard STS for CI/CD
• Melange (Go-based APK builder)
• Apko (Go-based OCI image builder)
• Docker/OCI Registry (cgr.dev), HTTP server for APK repo
• YAML manifest format, Make, shell scripts for orchestration