Documentation & UX Request: Guidance for Replicating Official Images and Multi-Arch Builds

[martinn-ronin]

User Perspective
As a user familiar with Docker-style declarative builds, I find the transition to rpi-image-gen quite steep. While the tool is powerful, the current documentation focuses on "minimal base" examples that don't clearly demonstrate how to bridge the gap to a fully-featured or official-style Raspberry Pi OS image.

The Problem

1. Replicating Official Builds: There are no clear templates for building the equivalent of an official "Lite" or "Desktop" image. Starting from a blank slate to reach that level of feature-parity is currently a manual "trial and error" process.
2. Multi-Architecture Complexity: Building for armhf (32-bit) vs. arm64 (64-bit) feels complex. Unlike the simple --platform flag in Docker, it is not immediately clear how to handle architecture-specific package names or configurations within the YAML layers.
3. The "Stripping Down" Workflow: Many users prefer to start with a known-good configuration (like an official image) and strip it down. The current documentation doesn't provide a clear path for this "subtractive" approach in a declarative way.

Requested Improvements

• Official Baseline Templates: Please provide official YAML configuration templates that exactly replicate the current "Lite" and "Standard" Raspberry Pi OS releases (for both architectures).
• Cross-Arch Guide: A dedicated section or "Cheat Sheet" explaining how to manage multi-arch builds, specifically how the --architecture flag interacts with package selection in YAML.
• Advanced Customization Examples: More complex examples showing how to transition from a minbase build to a production-ready OS with standard utilities (networking, SSH, common drivers) pre-configured.

Additional Context
Providing these "Baseline Templates" would allow users to treat them as a "Base Image" (similar to a Docker FROM instruction), making the tool much more accessible for building production-grade customized images.

[learmj]

Hi @martinn-ronin Thanks for your questions and interest in rpi-image-gen. My initial response to your problem items are below. I'm more than happy to work things through so you can get to where you need to be with the tool, but first:

1. Replicating Official Builds:

There are intentionally no configurations in the tree at the moment which build an official Raspberry Pi OS image. At the current time, there are no immediate plans to move generation of the official images from pi-gen to rpi-image-gen.

(I'll answer 3 next)

3. The "Stripping Down" Workflow:
   Many users prefer to start with a known-good configuration (like an official image) and strip it down.

This is one of the big problems we see. Firstly, it's bad for several reasons, including:

• Hidden baggage: hard to be sure you’ve removed all services, binaries, default users/passwords, debug tools, and auto-updaters that you don't need for your deployment. Net result - your attack surface is larger.
• Traceability: stripping a prebuilt image is a manual process - it's harder to version, audit, and recreate for SBOM and compliance. Net result - larger effort, compliance problems.
• Size/boot/IO: you carry extra packages, data, docs, binaries and a boot flow you didn’t plan for, increasing on-disk footprint and startup time. Net result - bloated image, non-deterministic startup and boot flow/time.
• Policy drift: defaults (systemd units, network config, ssh, and other services) may reappear on update or differ across OS releases. Net result - non-deterministic system, nasty run-time surprises.
• Update strategy: starting from a monolithic image makes controlled/pinned updates, CVE response, and signed artefacts more complex. Net result - compliance problems, security posture problems.

The "subtractive approach" is not something we endorse or recommend for devices which have a defined or bespoke use-cases, eg in-field embedded device, mission critical industrial controller, etc.

Like other widely used and well adopted build systems (eg Yocto), rpi-image-gen is intended for users who want to build their system from the ground up rather than subtracting things from the top down.

2. Multi-Architecture Complexity:

The rpi-image-gen layer system is described in detail here. A layer comprises of two parts - metadata and YAML. The metadata is understood by the engine that underpins the tool and the YAML is understood by bdebstrap (which is basically a modular wrapper for mmdebstrap). Specifying architecture type is as simple as using things like the following in the , eg:

mmdebstrap:
 architectures:
   - armhf

or

mmdebstrap:
  architectures:
    - arm64

etc
Take a look at some of the files in layer/. Omitting the architecture from all aggregated layers makes mmdebstrap use the native of the host.

Official Baseline Templates:

We may add configurations which can be used to construct a 'lite' or 'desktop' system, but they are unlikely to have exact parity with those generated by pi-gen, particularly because it's already possible today to generate yourself a bootable desktop system simply by installing rpd-wayland-core on op of a minimal image (a lot of development effort went into the new 'meta packages' available in Trixie).

Cross-Arch Guide:

Touching on a very interesting topic, certainly w.r.t. the Debian universe where the binaries are pre-built. rpi-image-gen does run in non-native arm64 environments. From the project's README:

...It expects a Debian-based system and can run in containers or on non-arm64 hosts via QEMU, but those environments are not formally supported. The build invokes mmdebstrap to create a chroot and mount pseudo-filesystems (proc, sysfs, devpts) inside a private mount namespace, which requires CAP_SYS_ADMIN or equivalent (eg, --privileged or --security-opt=unconfined depending on rootless/container setup).

...so it is possible to construct a chroot intended for your device which has binaries that differ from your build host architecture (ie cross). With that said, emulation is slow (eg initramfs image build running on emulation is painful). Containerised builds are widely used these days and we have customers that spin up containers on server clusters, run builds with rpi-image-gen, copy off build assets, and terminate the container.

Everyone's workflow is different. My own view is that I would like rpi-image-gen to interoperate with as many of them as possible, and I'm certainly open to improving the documentation.

Let me know what you think of the above...

[martinn-ronin]

Thank you for the feedback, I understand completely. I definitely want to move away from my current "post-flash" scripts and toward a proper image-building workflow to reduce bloat; this tool seems like the perfect way to do that.

I do have a few specific constraints I'm trying to navigate:

1. Architecture (armhf): Our software stack is currently compiled for armhf and won't run on arm64. We have many devices in the field that require this compatibility, so being able to build an armhf image is a hard requirement for our next design phase.

2. Environment (WSL2/Debian): I am fully aware that using WSL and Debian is not the recommended or supported environment for this tool. However, it is currently the only resource at my disposal. I’m struggling to make headway on an armhf build in this environment, as the documentation for targeting that specific architecture is a bit unclear to me.

3. Learning Curve: I am the only person on my team with Linux knowledge, but I haven’t yet reached the advanced stage of building images from scratch. I see how powerful rpi-image-gen is, but I’m finding it difficult to bridge the gap between the default examples and our specific needs.

Any guidance or examples on how to correctly configure a build for armhf (specifically within a WSL/Debian context, if possible) would be incredibly helpful as I try to modernize our deployment process.

I did follow some videos explaining structure and setup but it appears to have changed since the recent restructuring of the tool

[martinn-ronin]

Update: Based on the earlier reply from @learmj , I understand that there currently aren’t any official templates in the repository for producing Raspberry Pi OS-equivalent images or multi-architecture builds (e.g., armhf). However, I’ve now tested this hands-on:

I set up a Raspberry Pi 4 using the latest ARM64 Raspberry Pi OS host image. I then created a custom layer depending on trixie-minbase.yaml, and explicitly configured mmdebstrap for armhf as described in the documentation.

Despite that, every build still results in an ARM64 userland rather than an ARMHF userspace. I confirmed the architecture of the produced filesystem to verify this.

So even when targeting armhf explicitly via mmdebstrap and YAML configuration, the result remains arm64 when running on an ARM64 host. If generating ARMHF output is not currently supported on an ARM64 host, documenting this limitation or providing a clear configuration path would help avoid confusion.

Please clarify whether armhf builds are expected to work with the current toolchain and configs, and if so, what additional steps or flags are required to force an armhf userspace.

Thanks!

[learmj]

Hi @martinn-ronin
You can construct a system where you can run 32-bit userspace apps. In fact the default configuration provides exactly that.
config/trixie-minbase.yaml -> layer trixie-minbase (layer/suite/debian/trixie-minbase.yaml) -> X-Env-Layer-Requires: debian-trixie-arm64-multi (layer/debian/trixie/arm64/base-apt-multi.yaml) which defines:

mmdebstrap:
  architectures:
    - arm64 armhf

..so you will be able to execute a program compiled for armhf on this system without any problem.
In the above configuration, arm64 is the native architecture (specified first) and armhf is classed as a 'foreign' architecture.

Is there a particular reason that you require 32-bit native userspace?

It's possible to generate a system that only has 32-bit userspace by using raspbian packages, but please note that while these are linked to by Raspberry Pi, raspbian packages are not supported by Raspberry Pi.

There is a layer in the tree you can use. raspbian-trixie-armhf will provide a 32-bit native userland. You can use this instead of debian-trixie-arm64-multi.

[learmj]

Hi @martinn-ronin How are you getting on?

[martinn-ronin]

@learmj apologize for the late reply, I have tried to get a working armhf image however I do appear to possibly not fully understand how to use the tool just yet. Unfortunately the binaries we use require a armhf user land and overcoming this has proved rather challenging. I have attempted to use the raspbian-trixie-armhf as my base but ran into issues of localization not ready or something along those lines, currently I have put a hold on this however I will attempt again in the future to overcome the challenge of not being able to successfully build an armhf image. I do also look forward to some more simple and more common examples for those whom aren't familiar with building images to get a better understanding of how to achieve my final goal

[learmj]

fyi see #207