Build, customize, and maintain production-ready Raspberry Pi images with ease.

A modular automated build system for creating custom Raspberry Pi OS images with full hardware support, automatic updates, and service composition.

Building and maintaining custom Raspberry Pi images is traditionally complex and error-prone. This project solves that by providing:

• Easy Image Creation - Build custom images with a single command
• Modular Service System - Compose images from reusable service components
• Automatic Hardware Support - Full Raspberry Pi hardware compatibility maintained automatically
• CI/CD Integration - Automated builds and releases via GitHub Actions
• Auto-Detection - Network interfaces, WiFi adapters, and USB devices automatically configured
• Safe Updates - apt upgrade works without breaking hardware support
• Share & Maintain - Version control your image configurations, share with your team

Build images by combining service modules:

# Base Debian image
./bin/autobuild --image debian

# Debian + Incus + Docker
./bin/autobuild --image debian/qemu+docker

# Full stack: Incus + Docker + OpenWrt + Home Assistant + WiFi Hotspot
./bin/autobuild --image debian/qemu+docker+openwrt+hotspot+haos

Available services:

• qemu - Incus container/VM platform with KVM acceleration
• docker - Docker Engine with Portainer and Watchtower
• haos - Home Assistant OS in an Incus VM
• openwrt - OpenWrt router in an Incus container
• hotspot - WiFi access point (2.4GHz/5GHz)

• Network Interfaces - Dual NIC? Automatic bridge configuration (br-wan + br-lan)
• WiFi Adapters - Dual-band WiFi? Auto-configures 2.4GHz + 5GHz access points
• Zigbee Dongles - USB Zigbee coordinators auto-passed to Home Assistant VM
• Adaptive Configuration - Services adapt to available hardware

• Automated Builds - Daily builds or on-demand via GitHub Actions
• Multi-Stage Pipeline - Parallel builds for faster releases
• Automatic Releases - Compressed images uploaded to GitHub Releases
• Branch Strategy - Stable releases on main, pre-releases on test/preview branches

RaspiOS kernel and firmware packages are integrated via APT with pinning:

# Update everything safely
sudo apt update && sudo apt upgrade -y

Kernel, firmware, and WiFi/Bluetooth drivers update from RaspiOS repositories while all other packages update from Debian - no manual intervention required.

sudo apt install -y parted e2fsprogs dosfstools qemu-utils rsync \
                    xz-utils genisoimage qemu-system-aarch64

# Clone the repository
git clone https://github.com/Pikatsuto/raspberry-builds.git
cd raspberry-builds

# Build a base Debian image
./bin/autobuild --image debian

# Or build with services
./bin/autobuild --image debian/qemu+docker

# Flash to SD card
sudo dd if=debian-*.img of=/dev/sdX bs=4M status=progress conv=fsync

# Copy the base configuration
cp -r images/debian images/myproject

# Edit configuration
vim images/myproject/config.sh
# Set OUTPUT_IMAGE, IMAGE_SIZE, SERVICES, etc.

# Customize setup
vim images/myproject/services/base/setup.sh
# Add your package installations

# Build
./bin/autobuild --image myproject

• Getting Started - Installation, first build, flashing
• Architecture - How the build system works
• Build System - Autobuild options, multi-stage pipeline
• Service System - Creating and using service modules
• GitHub Actions - CI/CD setup and workflows
• Hardware Detection - Auto-configuration features
• FAQ - Common questions and troubleshooting

Build a Raspberry Pi home server with Docker, Portainer, and automatic hardware support.

Create an IoT gateway with Home Assistant, Zigbee coordinator auto-detection, and dual WiFi AP.

Build a custom router with OpenWrt in a container, dual NIC bridge configuration, and WiFi hotspot.

Create reproducible development environments with Incus containers/VMs and Docker.

Version control image configurations, build via CI/CD, deploy identical images across multiple devices.

1. Base Images - Downloads Raspberry Pi OS (boot/firmware) + Debian ARM64 (rootfs)
2. Service Composition - Combines setup scripts from selected services
3. QEMU Build - Installs packages in ARM64 QEMU VM, including RaspiOS kernel/firmware
4. Merge - Keeps RaspiOS boot partition, replaces root with configured Debian
5. Compress - PiShrink + xz compression for minimal image size

The result is a Debian ARM64 userspace with full Raspberry Pi hardware support and automatic updates.

Current Support:

• Raspberry Pi 4/5 (ARM64)
• Debian 13 (Trixie) ARM64
• Automatic hardware detection (network, WiFi, USB Zigbee)

In Development:

• Additional distribution support (Ubuntu, Fedora, Alpine)
• Expanded hardware detection (storage, audio, camera)

Contributions welcome! See CONTRIBUTING.md for guidelines.

This project is licensed under the MIT License - see LICENSE for details.

• Issues - GitHub Issues
• Discussions - GitHub Discussions
• Wiki - Documentation Wiki

Built with Raspberry Pi OS + Debian ARM64 + QEMU + GitHub Actions