Jan De Landtsheer
7eb27ff376
CRITICAL FIXES: - Fix build-initramfs.sh early exit preventing zinit installation - Add binary detection/installation logic to setup-initramfs.sh - Ensure compiled components are properly installed to initramfs DOCUMENTATION: - Update README.md to reflect actual implementation - Document source compilation approach with git submodules - Add development workflow and caching documentation - Remove outdated GitHub releases references This fixes the 'zinit not found' boot error by ensuring the build pipeline completes all phases including initramfs assembly.
125 lines
4.7 KiB
Markdown
125 lines
4.7 KiB
Markdown
# 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
|
|
```bash
|
|
# Build everything
|
|
./build.sh
|
|
|
|
# Or with Docker Compose
|
|
cd build/
|
|
docker-compose up
|
|
```
|
|
|
|
### Development Build
|
|
```bash
|
|
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)
|
|
```bash
|
|
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
|
|
```bash
|
|
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
|
|
```bash
|
|
# 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 |