deb-bootc-image-builder/docs/bluebuild.md

BlueBuild Ecosystem: Comprehensive Analysis

Date: August 17, 2025
Status: Active and Well-Maintained
License: Core tools (Apache-2.0), Workshop (AGPL-3.0)

---

🎯 Executive Summary

The BlueBuild project is an integrated ecosystem of tools designed to simplify and automate the creation of custom, immutable operating system images, with a primary focus on Fedora Atomic distributions such as Silverblue and Kinoite.

Core Value Proposition

• Declarative Configuration: Replace complex manual scripting with straightforward YAML files
• Container-Centric Design: Leverage modern container technologies for reproducible builds
• Security-First Approach: Deep integration with Sigstore for cryptographic signing
• CI/CD Native: Seamless integration with automated pipelines
• Developer Experience: Multiple installation methods and comprehensive tooling

Mission Statement

Lower the barrier to entry for both individual developers and larger organizations to build and maintain personalized, reproducible, and secure Linux environments.

---

🏗️ Architectural Overview

Unifying Philosophy

The BlueBuild ecosystem is built around the principle of declarative configuration, where the desired state of the operating system image is defined in a single recipe.yml file. This approach abstracts away the complexities of the underlying build process, providing a consistent and repeatable experience.

Core Architecture Components

The ecosystem is composed of several interdependent repositories, each fulfilling a specific function within the overall architecture:

Component	Repository	Primary Function	Key Dependencies
CLI Orchestrator	blue-build/cli	Primary build orchestrator and user interface	blue-build/modules, Docker/Podman/Buildah
Project Template	blue-build/template	Canonical starter kit for new projects	None (acts as foundation)
Module Library	blue-build/modules	Reusable, standardized building blocks	blue-build/cli (consumed by)
CI/CD Automation	blue-build/github-action	GitHub Actions integration	blue-build/cli (wraps)

---

🔧 Core Components Deep Dive

1. The Command-Line Interface (blue-build/cli)

The blue-build/cli is the central command-line program that orchestrates the entire image build process based on a recipe.yml file.

Key Features

• Modern Container Build Features: Leverages bind, cache, and tmpfs mounts on RUN instructions
• Multi-Engine Support: Compatible with Docker v23+, Podman v4+, and Buildah v1.29+
• Performance Optimization: Enhanced performance and reproducibility through advanced mount strategies

Core Commands

Command	Description	Example Syntax
generate	Converts recipe.yml to Containerfile	bluebuild generate ./recipes/recipe.yml -o Containerfile
build	Directly builds custom image from recipe.yml	bluebuild build ./recipes/recipe.yml
switch	Builds and locally rebases to new image	bluebuild switch recipes/recipe.yml
completions	Generates shell completion scripts	bluebuild completions bash

Installation Methods

• Cargo: cargo install bluebuild-cli
• Standalone Binary: Using podman or docker run commands
• Bash Script: Simple installation script
• Rootless Alpine: Distrobox image for rootless operation
• Nix Integration: Comprehensive Nix flakes support through FlakeHub

2. The Project Template (blue-build/template)

The blue-build/template repository is a public GitHub template that acts as a canonical starter kit for anyone wishing to create a custom OS image.

What It Provides

• Essential Files: Pre-configured .github directory for CI workflows
• Recipe Structure: Organized recipes folder for declarative configuration
• Security Setup: cosign.pub file for image verification
• Project Structure: Consistent folder organization across the ecosystem

Strategic Significance

The project's decision to deprecate the blue-build/legacy-template repository in favor of this new, unified template demonstrates:

• Active Maintenance: Project is actively maintained and evolving
• Consolidation: Strategic move to streamline offerings
• Mature Development: Clear future direction and product evolution

3. The Building Blocks (blue-build/modules)

Modules are the cornerstone of the BlueBuild architecture, serving as self-contained, script-based components executed during the image build process.

Module Types

Type	Execution Time	Use Case	Preference
Build-time	During image build	System reliability, package installation	Preferred
Run-time	At system boot	When build-time not feasible	Secondary choice

Module Structure

Each public module includes:

• module.yml: Metadata and configuration
• README.md: Comprehensive documentation
• .tsp: TypeSpec schema for configuration validation
• Compiled JSON Schema: Automated validation in CI pipelines

Configuration Management

• System Configuration: Read-only configuration derived from recipe.yml
• Local User Configuration: Writable configuration for end-user customization
• Separation of Concerns: Maintainers control base, users customize experience

Module Configuration Options

Option	Description	Mandatory/Optional
type	Name of the module to run	Mandatory
source	URL of module repository	Optional
no-cache	Skip cache when true	Optional
env	Environment variables list	Optional
secrets	Secrets to mount	Optional

4. The CI/CD Automator (blue-build/github-action)

The blue-build/github-action repository provides a reusable GitHub Action specifically designed to automate the process of building custom operating system images.

Key Features

• Seamless Integration: Wraps the core blue-build/cli tool
• Automated Workflow: Build, sign, and publish images automatically
• Platform Compatibility: Examples and support for both GitHub and GitLab
• Consistent Behavior: Same build process locally and in CI

---

🔄 Workflow Analysis

Developer Workflow

The developer workflow with BlueBuild is focused on an iterative, test-driven approach:

1. Project Setup: Clone from template repository
2. Configuration: Configure recipe.yml file
3. Local Testing: Use bluebuild cli for local testing
4. Preview: Use generate command to inspect Containerfile
5. Build: Use build command for direct image creation
6. Iterate: Test changes locally before pushing to remote

Key Benefits

• Consistency: Local build command matches CI environment
• Reduced Friction: What works locally works in automated pipeline
• Debugging: Generate command allows manual inspection

End-User Workflow

For end-users, adopting a custom image built with BlueBuild is a straightforward two-step rebase operation:

Step 1: Initial Rebase to Unsigned Image

• Installs necessary signing keys and policies
• System reboot required

Step 2: Rebase to Final Signed Image

• Rebase to cryptographically signed image
• Second reboot completes process

Security Features

• Two-Step Process: Ensures public keys are installed before trusted image
• Latest Tag Management: Always points to most recent build
• Version Stability: Tied to major Fedora version, preventing accidental upgrades

---

🔒 Security and Integrity

Sigstore Integration

Security is a first-class citizen in the BlueBuild ecosystem, with deep and consistent integration with Sigstore's cosign tool for image signing.

Security Features

• Image Signing: Core part of CI workflow
• Supply Chain Security: Critical for image integrity and origin verification
• Public Key Verification: cosign.pub file included in template repository
• Cryptographic Signing: All built images are cryptographically signed

Advanced Security Tools

WASM Cosign Key Generation

The blue-build/wasm-cosign-keygen repository generates cosign keys in the browser using WebAssembly:

• Production Ready: Actively used by BlueBuild Workshop
• Accessibility: Lowers technical barrier to secure key pair creation
• User-Friendly: Enables broader participation in secure signing process

---

📚 Supporting and Strategic Repositories

Security and Integrity

Repository	Purpose	Status	Significance
blue-build/wasm-cosign-keygen	Browser-based key generation	Production Ready	Security accessibility
blue-build/jsonschema	TypeSpec schema compilation	Active Development	Configuration validation

Real-World Applications

blue-build/nushell-image

• Purpose: Create OCI images of Nushell command shell
• Schedule: Weekly automated builds
• Features: Version tagging, cryptographic signing
• Significance: Demonstrates toolchain versatility beyond OS images

blue-build/workshop

• Purpose: Web application and Tauri app for GUI interaction
• Status: Work in Progress - Active development
• Features: SSR web version, Tauri desktop app, GitHub OAuth
• Strategic Value: Future vision for GUI-driven platform

Development Infrastructure

Repository	Purpose	Status	Role
blue-build/earthly-lib	Library of earthly functions	Active	Internal build orchestration
blue-build/examples	Best practices and use cases	Work in Progress	User onboarding and documentation

---

📊 Current Development Momentum

Enhanced CLI Capabilities

Multiple Installation Methods

• Distrobox Integration: Alpine-based image for rootless operation
• Nix Integration: Comprehensive FlakeHub support
• Cross-Platform: Available across different development environments

User Experience Improvements

• switch Command: Build and immediately rebase local system
• Automatic Reboot: Optional --reboot/-r flag
• Local Testing: Significant improvements for development workflows

CI/CD Platform Maturity

GitHub Actions Integration

• Comprehensive examples and workflows
• Automated build, signing, and publication
• Secure key management integration

GitLab CI Support

• Specific guidance for GitLab integration
• Secure Files feature for cosign private keys
• Broader platform compatibility

---

🏢 Enterprise Readiness

Security Posture

• Production Security: WASM cosign tooling actively deployed
• Supply Chain Security: Comprehensive image signing and verification
• Audit Trail: Cryptographic proof of image origin and integrity

CI/CD Integration

• Automated Workflows: Consistent build processes across environments
• Platform Support: GitHub Actions, GitLab CI, and more
• Reproducibility: Same build process locally and in automation

Scalability Features

• Modular Architecture: Reusable components for complex workflows
• Configuration Management: Separation of system and user configurations
• Documentation: Comprehensive guides and examples

---

🚀 Future Direction Insights

GUI Interface Development

The workshop project shows active development with:

• SSR Web Version: Server-side rendered web application
• Tauri Desktop App: Cross-platform desktop application
• GitHub OAuth: Development environment integration
• Production Readiness: Progressing toward production deployment

Ecosystem Expansion

• Beyond OS Images: Nushell-image demonstrates OCI artifact versatility
• Automated Workflows: Weekly builds with proper signing
• Platform Diversity: Support for multiple CI/CD platforms

---

⚠️ Potential Areas for Enhancement

1. Documentation Consolidation

• Current State: Well-documented but distributed across repositories
• Challenge: May create discoverability challenges for new users
• Recommendation: Consider centralized documentation hub

2. Schema Management Evolution

• Current State: Apparent change in jsonschema repository approach
• Challenge: Ongoing evolution in configuration validation
• Recommendation: Clarify schema management in user-facing documentation

3. Enterprise Adoption Acceleration

• Current State: Robust CI/CD integration and security features
• Opportunity: Explicit enterprise-focused documentation and examples
• Potential: Accelerate adoption in enterprise environments

---

🎯 Strategic Recommendations

For Individual Developers

BlueBuild is a powerful and accessible tool for personalizing and maintaining custom, immutable OS images:

• Excellent Local Support: Rapid iteration and testing capabilities
• Comprehensive Tooling: Multiple installation methods and workflows
• Security Focus: Built-in cryptographic signing and verification

For Teams and Enterprises

Highly suitable for creating standardized, auditable, and reproducible company-wide images:

• CI/CD Integration: Seamless automation of build processes
• Image Signing: Enhanced software supply chain security
• Modular Architecture: Reusable components for complex workflows
• Documentation: Comprehensive guides and examples

---

🏆 Conclusion

The BlueBuild project represents a cohesive and well-engineered ecosystem for creating custom, immutable operating system images. It is built on a strong foundation of open-source components and a pragmatic, declarative design philosophy.

Key Strengths

• Modularity: Container-centric approach simplifies complex OS building
• Security: Deep integration with Sigstore and comprehensive signing
• CI/CD Native: Seamless integration with automated platforms
• Developer Experience: Multiple installation methods and comprehensive tooling

Current Status

While the project is still evolving, evidenced by the deprecation of legacy components and active workshop development, these are signs of an active and forward-looking development team.

Learning Curve vs. Power

The reliance on multiple repositories and external tools may present a learning curve for newcomers, but this is a reasonable trade-off for the power and flexibility that the architecture provides.

Overall Assessment

BlueBuild is a mature and forward-looking project that offers a robust solution for a growing niche in the Linux desktop and server space. It successfully bridges the gap between containerization and operating system management, providing a modern alternative to traditional, stateful Linux installations.

---

📚 Additional Resources

Core Documentation

• BlueBuild CLI Documentation
• Module Library
• Project Template
• GitHub Action

Examples and Use Cases

• Nushell Image Example
• Workshop Project
• Examples Repository

Security Tools

• WASM Cosign Keygen
• JSON Schema Validation

---

Last Updated: August 17, 2025
Analysis Status: Comprehensive and Current
Ecosystem Health: Active and Well-Maintained
Future Outlook: Promising with Active Development