Hi everyone,
Like many of you, I frequently use Docker for my Pi projects and homelab testing. However, I was always a bit frustrated by the lack of an official Raspberry Pi OS base image on Docker Hub. While standard Debian images work for many things, they lack the specific tweaks and packages native to Raspberry Pi OS.
To solve this, I created an automated pipeline to build and publish clean, pure Raspberry Pi OS Docker images.
Links:
I wanted this to be as close to "official" as functionally possible. The images are not modified Debian bases.
Instead, a GitHub Action downloads the official Raspberry Pi OS Lite .img.xz releases directly from downloads.raspberrypi.com. It uses libguestfs-tools (specifically guestfish) to extract the root filesystem from the image file, strips out hardware-specific mount points (/dev, /proc, /sys, /boot), and copies the raw rootfs into an empty scratch Docker container.
Key Features
You can use it as a base in your Dockerfiles:Or test it directly on your Pi (or an x86 machine with QEMU/binfmt installed):I built this primarily to scratch my own itch, but I’m sharing it here hoping it saves some of you time when building Pi-native container pipelines.
I would love any feedback, suggestions, or Pull Requests from the community to make this even better.
Cheers!
Vasco Guita
Like many of you, I frequently use Docker for my Pi projects and homelab testing. However, I was always a bit frustrated by the lack of an official Raspberry Pi OS base image on Docker Hub. While standard Debian images work for many things, they lack the specific tweaks and packages native to Raspberry Pi OS.
To solve this, I created an automated pipeline to build and publish clean, pure Raspberry Pi OS Docker images.
Links:
- Docker Hub: vascoguita/raspios
- GitHub (Source & Pipeline): vascoguita/raspios-docker
I wanted this to be as close to "official" as functionally possible. The images are not modified Debian bases.
Instead, a GitHub Action downloads the official Raspberry Pi OS Lite .img.xz releases directly from downloads.raspberrypi.com. It uses libguestfs-tools (specifically guestfish) to extract the root filesystem from the image file, strips out hardware-specific mount points (/dev, /proc, /sys, /boot), and copies the raw rootfs into an empty scratch Docker container.
Key Features
- True Multi-Architecture: Supports arm64, arm/v7, and even arm/v6 (for older Pi models).
- Rolling & Immutable Tags:
- Use arm64 or armhf to always track the latest release.
- Use date-stamped tags (e.g., arm64-20251204) for strict reproducibility. They will never be overwritten.
- Transparent CI/CD: The entire build matrix is automated via GitHub Actions, meaning updates are prompt and the process is entirely open for auditing.
You can use it as a base in your Dockerfiles:
Code:
FROM vascoguita/raspios:arm64# Add your custom Pi-specific layers hereCode:
docker run --rm -it --platform linux/arm64 vascoguita/raspios:arm64I would love any feedback, suggestions, or Pull Requests from the community to make this even better.
Cheers!
Vasco Guita
Statistics: Posted by vascoguita — Tue Mar 03, 2026 10:53 pm — Replies 0 — Views 21