zosbuilder/README.md

Alpine-based Zero-OS Initramfs

Modern Alpine Linux based approach to building Zero-OS initramfs with source compilation for Zero-OS components and Alpine packages for system tools.

Architecture Overview

This system uses:

• Alpine Linux 3.22 as base system with latest packages
• Rust workspace with git subtrees for Zero-OS Rust components (zinit, mycelium, rfs)
• Unified compilation via cargo build --workspace for all Rust components
• Alpine packages for system tools (busybox, openssh, btrfs-progs, etc.)
• Smart caching with Docker layers and volumes
• Same init flow as original Zero-OS

Directory Structure

alpine-initramfs/
├── Cargo.toml                 # Rust workspace configuration
├── build/                     # Build orchestration
│   ├── Dockerfile.alpine      # Alpine build environment
│   ├── Dockerfile.cached      # Multi-stage cached build
│   └── docker-compose.yml     # Build orchestration with caching
├── components/                # Git subtrees (Rust workspace members)
│   ├── zinit/                 # Init system (Rust subtree)
│   ├── mycelium/              # Networking layer (Rust subtree)
│   └── rfs/                   # Filesystem (Rust subtree)
├── configs/                   # Configuration files
│   ├── packages-alpine.txt    # Alpine packages to install
│   ├── kernel-version         # Kernel version to build
│   ├── kernel-config-generic  # Kernel configuration
│   ├── init                   # Init script (Alpine → zinit)
│   └── zinit/                 # Zinit service configurations
├── scripts/                   # Build scripts
│   ├── build-initramfs.sh     # Main build orchestrator
│   ├── compile-components.sh  # Compile Rust workspace
│   ├── fetch-github.sh        # Download CoreX binary
│   ├── install-packages.sh    # Install Alpine packages
│   ├── setup-initramfs.sh     # Create initramfs structure
│   ├── build-kernel.sh        # Build kernel with embedded initramfs
│   ├── build-smart.sh         # Smart build with caching
│   └── cleanup.sh             # Clean build artifacts
├── target/                    # Rust workspace build artifacts
├── output/                    # Final build outputs
│   ├── vmlinuz.efi            # Final bootable kernel
│   ├── initramfs.cpio.xz      # Generated initramfs
│   └── version.txt            # Build information
└── docs/                      # Documentation
    ├── BUILD.md               # Build process guide
    ├── OVERVIEW.md            # Architecture overview
    └── *.md                   # Additional documentation

Build Flow

1. Environment Setup: Alpine Docker container with Rust and build tools
2. Workspace Compilation: Single cargo build --workspace for all Rust components
3. Binary Downloads: Download CoreX (Go binary) from GitHub releases
4. Package Installation: Install Alpine packages to initramfs root
5. Initramfs Assembly: Create filesystem structure with compiled binaries
6. Kernel Build: Compile kernel with embedded initramfs
7. Output: Generate bootable vmlinuz.efi

Quick Start

Full Build

# Build everything
./build.sh

# Or with Docker Compose
cd build/
docker-compose up

Development Build

cd build/
# Interactive development shell
docker-compose run dev-shell

# Build entire workspace
cargo build --workspace --release --target x86_64-unknown-linux-musl

# Build specific component
cargo build -p zinit --release --target x86_64-unknown-linux-musl
cargo build -p mycelium --release --target x86_64-unknown-linux-musl
cargo build -p rfs --release --target x86_64-unknown-linux-musl

Smart Build (with caching)

cd build/
docker-compose run builder  # Uses build-smart.sh automatically

Key Features

• ✅ Rust workspace - Unified build system for all Rust components
• ✅ Git subtrees - Source code included, no submodule complexity
• ✅ Single build command - cargo build --workspace builds everything
• ✅ Shared dependencies - Consistent versions across all components
• ✅ Smart caching - Docker layer and volume caching for fast rebuilds
• ✅ Alpine packages - System tools from Alpine repositories
• ✅ Development mode - Full IDE support and integrated tooling
• ✅ Same functionality - 100% compatible with original Zero-OS

Development

Building Individual Components

cd build/
docker-compose run dev-shell

# Inside container - workspace build:
cargo build --workspace --release --target x86_64-unknown-linux-musl

# Or build specific packages:
cargo build -p zinit --release --target x86_64-unknown-linux-musl
cargo build -p mycelium --release --target x86_64-unknown-linux-musl
cargo build -p rfs --release --target x86_64-unknown-linux-musl

Cleanup

# Clean all build artifacts
./scripts/cleanup.sh

Cache Management

Smart build uses Docker volumes for caching:

• build-cache: Build state markers
• source-cache: Downloaded sources
• kernel-cache: Kernel builds
• target-cache: Rust workspace build artifacts

Updating Components

Update git subtree components:

# Update zinit to latest
git subtree pull --prefix=components/zinit https://github.com/threefoldtech/zinit.git master --squash

# Update mycelium to latest
git subtree pull --prefix=components/mycelium https://github.com/threefoldtech/mycelium.git master --squash

# Update rfs to latest
git subtree pull --prefix=components/rfs https://github.com/threefoldtech/rfs.git master --squash