dokmic/rpi

By dokmic

Updated about 1 month ago

Yet another unofficial Docker image of Raspberry Pi OS

Image
Internet of Things
Operating Systems
Developer Tools

689

Raspberry Pi OS Docker Image

VersionLicense

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.

Features

  • Optimized for Docker Desktop.
  • Volumes support.
  • Power Management support.
  • cmdline.txt support.

Context

Motivation

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.

Performance Optimization

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.

Power Management Support

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.

Usage

The container can be started using the run command:

docker run -it dokmic/rpi

After the boot, it should be possible to log in with the default user pi and password raspberry.

SSH

To access the SSH service, the related port should be forwarded to the host system:

docker run -it -p 2222:22 dokmic/rpi
Custom Command

To 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 $?
Custom Parameters

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/rpi
Shared Volumes

To 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/rpi
Stopping Container

The container can be stopped using the kill and stop commands.

Or within the container using power management commands, e.g.:

sudo poweroff
Docker Compose

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

Parameters

NameDefaultDescription
RPI_CPU4The number of CPU cores.
RPI_RAM1GThe amount of available RAM.
RPI_PORT22/tcpThe space-separated set of ports forwarded inside the running container (e.g., 22/tcp 80/tcp 53/udp).
RPI_SSHtrueThe boolean flag enables the SSH server.
RPI_USERpiThe predefined user.
RPI_PASSWORDraspberryThe predefined user password.

Tags

License

WTFPL 2.0

Docker Pull Command

docker pull dokmic/rpi