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
• Git submodules for Zero-OS components (zinit, mycelium, rfs, corex)
• Source compilation for Zero-OS components (Rust/Go with musl static linking)
• 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/
├── build/                     # Build orchestration
│   ├── Dockerfile.alpine      # Alpine build environment
│   ├── Dockerfile.cached      # Multi-stage cached build
│   └── docker-compose.yml     # Build orchestration with caching
├── components/                # Git submodules
│   ├── zinit/                 # Init system (Rust)
│   ├── mycelium/              # Networking layer (Rust)
│   ├── rfs/                   # Filesystem (Rust)
│   └── corex/                 # Container control (static binary)
├── 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 Zero-OS components from source
│   ├── 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
│   ├── setup-submodules.sh    # Initialize git submodules
│   └── cleanup.sh             # Clean build artifacts
├── output/                    # Build artifacts
│   ├── 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, Go, and build tools
2. Component Compilation: Build zinit, mycelium, rfs from source (musl static)
3. Package Installation: Install Alpine packages to initramfs root
4. Initramfs Assembly: Create filesystem structure with compiled binaries
5. Kernel Build: Compile kernel with embedded initramfs
6. 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 specific component (e.g., mycelium)
cd /build/components/mycelium/myceliumd
cargo build --release --target x86_64-unknown-linux-musl

Smart Build (with caching)

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

Key Features

• ✅ Source compilation - Latest Zero-OS components with static linking
• ✅ Smart caching - Docker layer and volume caching for fast rebuilds
• ✅ Alpine packages - System tools from Alpine repositories
• ✅ Multi-stage builds - Efficient Docker builds with minimal layers
• ✅ Development mode - Interactive shell for component development
• ✅ Same functionality - 100% compatible with original Zero-OS
• ✅ Modern toolchain - Rust 1.x, Go latest, Alpine 3.22

Development

Building Individual Components

cd build/
docker-compose run dev-shell

# Inside container:
cd /build/components/mycelium/myceliumd && cargo build --release --target x86_64-unknown-linux-musl
cd /build/components/zinit && cargo build --release --target x86_64-unknown-linux-musl
cd /build/components/rfs && cargo build --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 build artifacts