This is an unofficial Docker image of Raspberry Pi OS running in QEMU.
Unlike others, this image is optimized to run inside a container with volumes support.
- Optimized for Docker Desktop.
- Volumes support.
- Power Management support.
cmdline.txtsupport.
Sometimes, testing your work on the Raspberry Pi OS is much easier without running it on real hardware. Things like Ansible Playbooks or a Kubernetes cluster, in most cases, can be tested in a virtualized environment.
There are plenty of tutorials and other Docker images running Raspberry Pi OS using QEMU, but all of them extract the OS image at runtime. Hence, they do not support mounting volumes to share the filesystem.
First off, the Docker image is running QEMU using the virt generic virtual platform.
The QEMU developers claim that it is designed for use in virtual machines.
As Docker Desktop is already running on a virtual machine, using the virt machine type gives a noticeable performance increase.
Another optimization is using the 9P passthrough filesystem. Compared to mounting a binary image, this filesystem significantly improves I/O throughput.
The image has a wrapper that restarts the virtual machine on reboot. On shutdown, the container is exited with a zero exit code.
If the OS kernel throws a panic, the panic code will be returned.
The reboot support without stopping the container simulates the cmdline.txt behavior.
That means the file can be edited, and the Raspberry OS kernel should pick up the updated options after the next reboot, just like the normal Raspberry Pi OS.
The container can be started using the run command:
docker run -it dokmic/rpiAfter the boot, it should be possible to log in with the default user pi and password raspberry.
To access the SSH service, the related port should be forwarded to the host system:
docker run -it -p 2222:22 dokmic/rpiTo override the kernel init command, the command argument in the run command should be specified:
docker run dokmic/rpi /bin/bash -c 'echo "hello world"'The image's entry point will also handle and forward the init process' exit code:
docker run -it dokmic/rpi /bin/bash -c 'exit 123'; echo $?Some of the parameters can be customized via the environment variables (e.g., CPU, RAM, or user credentials):
docker run -it -e RPI_USER=user -e RPI_PASSWORD=password dokmic/rpiTo share data from your host with the running Raspberry Pi OS, the Docker Volumes should be mounted below /media/sd:
docker run -it -v .:/media/sd/root/app dokmic/rpiThe container can be stopped using the kill and stop commands.
Or within the container using power management commands, e.g.:
sudo poweroff
It is also possible to create a service using Docker Compose:
services:
rpi:
environment:
- RPI_CPU
- RPI_PASSWORD
- RPI_PORT
- RPI_RAM
- RPI_SSH
- RPI_USER
image: dokmic/rpi:latest
ports:
- 2222:22| Name | Default | Description |
|---|---|---|
RPI_CPU |
4 |
The number of CPU cores. |
RPI_RAM |
1G |
The amount of available RAM. |
RPI_PORT |
22/tcp |
The space-separated set of ports forwarded inside the running container (e.g., 22/tcp 80/tcp 53/udp). |
RPI_SSH |
true |
The boolean flag enables the SSH server. |
RPI_USER |
pi |
The predefined user. |
RPI_PASSWORD |
raspberry |
The predefined user password. |
20241119-arm64,20241119,arm64,latest— Raspberry Pi OS Lite 64-bit ARM from 2024-11-19.20241119-arm,arm— Raspberry Pi OS Lite 32-bit ARM from 2024-11-19.20241113-arm64,20241113— Raspberry Pi OS Lite 64-bit ARM from 2024-11-13.20241113-arm— Raspberry Pi OS Lite 32-bit ARM from 2024-11-13.20241022-arm64,20241022— Raspberry Pi OS Lite 64-bit ARM from 2024-10-22.20241022-arm— Raspberry Pi OS Lite 32-bit ARM from 2024-10-22.20240704-arm64,20240704— Raspberry Pi OS Lite 64-bit ARM from 2024-07-04.20240704-arm— Raspberry Pi OS Lite 32-bit ARM from 2024-07-04.