Skip to content

Flashberry

Flashberry builds reproducible Raspberry Pi disk images inside Docker. It uses mmdebstrap to bootstrap a Debian-family root filesystem, QEMU user emulation for cross-architecture configuration, overlays and hooks for customization, and a dedicated flasher container for writing the finished image to an SD card.

What it gives you

  • Host isolation — the image toolchain runs in containers rather than being installed directly on the workstation.
  • Cross-architecture builds — build arm64, armhf, or arm root filesystems from a Linux host with binfmt/QEMU support.
  • Declarative configuration — hostname, locale, users, packages, Wi-Fi, and image settings live in YAML.
  • Layered customization — copy files through overlays and run deterministic shell hooks at defined build stages.
  • Release checks — configuration validation, shell checks, unit tests, Compose validation, version/changelog consistency, and checksum generation.
  • Safer flashing — Flashberry requires a whole block device, rejects mounted targets by default, and verifies compressed-image checksums when present.

Pipeline at a glance

flashberry.yml
      │
      ▼
  validate ──► prepare binfmt ──► mmdebstrap rootfs
                                      │
                                      ▼
                              configure in chroot
                                      │
                         overlays + hooks + packages
                                      │
                                      ▼
                              assemble disk image
                                      │
                                      ▼
                            compress + sha256
                                      │
                                      ▼
                              flash to SD card

Start here

  1. Read Getting started.
  2. Copy the tracked example into a private local configuration.
  3. Run the validation checks before starting a potentially long image build.
  4. Build and inspect the image.
  5. Read Flashing safely before writing a physical device.

Warning

Flashing is destructive. Always verify the target device and unmount all of its partitions before running the flash target.