Welcome to the Raspberry Pi Image Builder documentation! This system makes it easy to build, customize, and maintain production-ready Raspberry Pi images.

A modular automated build system that creates custom Raspberry Pi OS images by:

• Combining Raspberry Pi OS firmware with Debian ARM64
• Installing packages via QEMU ARM64 emulation
• Composing images from reusable service modules
• Automating builds via GitHub Actions CI/CD
• Auto-detecting and configuring hardware

• Installation & First Build
• Flashing Images to SD Cards
• First Boot & Login

• Architecture Overview
• Build System
• Service System

• Creating Custom Images
• Creating Custom Services
• GitHub Actions CI/CD
• Hardware Auto-Detection

• Available Images
• Available Services
• Command Reference
• Configuration Reference

• FAQ
• Troubleshooting
• GitHub Issues

# One command to build a custom image
./bin/autobuild --image debian/qemu+docker+haos

• Version control your image configurations
• Automated builds via GitHub Actions
• Safe apt upgrade - kernel and firmware update automatically

• Share image configurations with your team
• Reproducible builds across environments
• Pre-built images in GitHub Releases

• Modular service system
• Add your own services
• Full control over packages and configuration

• Modular Services - Compose images from qemu, docker, haos, openwrt, hotspot
• Auto-Detection - Network interfaces, WiFi, Zigbee dongles
• CI/CD Ready - GitHub Actions for automated builds
• Safe Updates - RaspiOS kernel via APT with pinning
• Full Hardware Support - RP1 drivers, WiFi, Bluetooth, GPIO

• Home Server - Docker + Portainer + Watchtower
• IoT Gateway - Home Assistant + Zigbee auto-detection
• Network Router - OpenWrt + WiFi hotspot + dual NIC
• Virtualization Platform - Incus containers and VMs
• Custom Appliance - Your own service modules

RaspiOS Boot Partition (FAT32)     Debian Rootfs (ext4)
├── bootloader                     ├── /bin, /usr, /etc (Debian)
├── kernel                         ├── RaspiOS kernel packages (via APT)
├── firmware                       ├── Your services
└── config.txt                     └── Auto-hardware detection
         ↓                                    ↓
         └────────── Merged Image ───────────┘

• Raspberry Pi 4/5 (ARM64)
• Debian 13 (Trixie) ARM64
• Additional distributions in development

1. Install dependencies and build your first image
2. Understand how the build system works
3. Explore available services
4. Create your own custom image

Happy Building!