docker-rgpio

This repo builds a Docker image that fetches the lg source from Clam-/lg, builds rgpiod and related libraries from source on top of a small Debian trixie-slim base, then exposes the rgpiod socket interface for remote GPIO access.

It is designed to be buildable directly from a Git URL, for example with docker buildx build https://github.com/....

It is also structured to work with the remote-client deployment model described in ha-docker-pxe-deploy: build the image from this Git repository on the Raspberry Pi client, then run it there with explicit ports, devices, and env settings instead of relying on Compose.

Easy image build and publish

The repo now includes a small buildx wrapper plus make targets so the normal workflow is a short command instead of a long Docker invocation.

Default target platform:

• linux/arm64

Prerequisites:

• Docker CLI installed
• buildx available either as docker buildx or standalone docker-buildx
• A working Docker daemon, or a Docker context that points at a reachable remote daemon
• For cross-building from a non-ARM host, buildx emulation support available to Docker

Build an arm64 image into your local Docker image store:

make image-build

Build against a different lg repo and tag:

make image-build LG_REPO=<owner>/lg LG_TAG=<tag>

Publish an arm64 image to a registry:

make image-publish IMAGE_REPO=ghcr.io/<owner>/docker-rgpio IMAGE_TAG=latest

Publish an image built from a different lg repo and tag:

make image-publish IMAGE_REPO=ghcr.io/<owner>/docker-rgpio IMAGE_TAG=latest LG_REPO=<owner>/lg LG_TAG=<tag>

Build and publish a specific version tag:

make image-publish IMAGE_REPO=ghcr.io/<owner>/docker-rgpio IMAGE_TAG=2026.03.15

The helper script automatically creates and bootstraps a dedicated buildx builder named docker-rgpio-arm64 if it does not already exist.

Supported variables:

• IMAGE_REPO: image repository/name, default docker-rgpio
• IMAGE_TAG: image tag, default latest
• IMAGE_PLATFORM: target platform, default linux/arm64
• BASE_IMAGE: base image build arg, default debian:trixie-slim
• LG_REPO: GitHub repo to build lg from, default Clam-/lg
• LG_TAG: Git tag to build from, default 202603-off-fix
• BUILDER_NAME: override the buildx builder name if needed
• EXTRA_ARGS: append raw extra flags to docker buildx build

If you prefer not to use make, the underlying helper is:

sh scripts/docker-image.sh build
sh scripts/docker-image.sh publish

The helper also accepts inline NAME=value overrides after the action:

sh scripts/docker-image.sh build LG_REPO=<owner>/lg LG_TAG=<tag>
sh scripts/docker-image.sh publish IMAGE_REPO=ghcr.io/<owner>/docker-rgpio IMAGE_TAG=latest LG_REPO=<owner>/lg LG_TAG=<tag>

Assumptions

• The supported target is a Raspberry Pi OS host running Docker on Raspberry Pi hardware.
• The image builds rgpiod from the Clam-/lg GitHub source tarball on top of a Debian trixie-slim base.
• The default build uses debian:trixie-slim.
• This still does not make GPIO portable across arbitrary hosts. The container needs Linux gpiochip device nodes from the host, typically /dev/gpiochip0 and sometimes additional gpiochips depending on the board.

Upstream source selection

• By default the image downloads the Clam-/lg tag 202603-off-fix and builds it during docker build.
• You can switch to another upstream repo or tag without editing the repo by overriding LG_REPO and LG_TAG.
• Using tags keeps builds reproducible. If you later need a different tag, pass it at build time.

Build from a GitHub URL

Build directly from the repo URL:

docker buildx build \
  -t docker-rgpio:latest \
  --build-arg BASE_IMAGE=debian:trixie-slim \
  --build-arg LG_REPO=Clam-/lg \
  --build-arg LG_TAG=202603-off-fix \
  https://github.com/<owner>/<repo>.git#main

The Dockerfile downloads the selected upstream lg tag from GitHub, builds it, and installs only the pieces needed to run rgpiod.

Override the upstream tag from the outside with either make variables or build args:

make image-build LG_TAG=202604-some-future-fix

You can override both source repo and tag the same way:

make image-build LG_REPO=<owner>/lg LG_TAG=<tag>

docker buildx build \
  -t docker-rgpio:latest \
  --build-arg LG_REPO=<owner>/lg \
  --build-arg LG_TAG=202604-some-future-fix \
  .

Home Assistant PXE Docker Fleet

This repository can be deployed either by pulling the published image or by building from Git. The example below now uses the published GHCR image.

Use a containers entry like this on the Raspberry Pi client:

[
  {
    "name": "rgpiod",
    "image": "ghcr.io/clam-docker-images/docker-rgpio:latest",
    "env": {
      "RGPIOD_PORT": "8889",
      "RGPIOD_LOCAL_ONLY": "0"
    },
    "ports": [
      "8889:8889"
    ],
    "devices": [
      "/dev/gpiochip0:/dev/gpiochip0"
    ]
  }
]

Notes for that add-on model:

• The example above pulls the published image directly from GHCR.
• If you prefer client-side builds on the Pi, you can still use source.type: git instead of a published image.
• Add more entries under devices if the target board exposes additional gpiochips.
• If you want to restrict access, set RGPIOD_LOCAL_ONLY=1 or provide RGPIOD_ALLOWED_IPS.
• The example JSON is also available in examples/ha-docker-pxe-deploy.containers.json.

Run on a Raspberry Pi OS host

Minimal device mapping:

docker run -d \
  --name rgpiod \
  --restart unless-stopped \
  --device /dev/gpiochip0:/dev/gpiochip0 \
  -p 8889:8889 \
  docker-rgpio:latest

If your board exposes more than one gpiochip, pass each needed device:

docker run -d \
  --name rgpiod \
  --restart unless-stopped \
  --device /dev/gpiochip0:/dev/gpiochip0 \
  --device /dev/gpiochip4:/dev/gpiochip4 \
  -p 8889:8889 \
  docker-rgpio:latest

Runtime configuration

Environment variables:

• RGPIOD_PORT: TCP port for rgpiod. Default: 8889
• RGPIOD_LOCAL_ONLY: set to 1 to disable remote socket access (rgpiod -l)
• RGPIOD_ALLOWED_IPS: comma-separated allow-list, translated to repeated rgpiod -n flags
• RGPIOD_ACCESS_CONTROL: set to 1 to enable access control (rgpiod -x)
• RGPIOD_CONFIG_DIR: optional config directory passed as rgpiod -c
• RGPIOD_WORK_DIR: optional working directory passed as rgpiod -w
• RGPIOD_SKIP_DEVICE_CHECK: set to 1 only if you intentionally want to bypass the startup device check

Extra rgpiod flags can be passed as container arguments:

docker run --rm \
  --device /dev/gpiochip0:/dev/gpiochip0 \
  -p 8889:8889 \
  docker-rgpio:latest \
  -n 192.168.1.10

Compose example

The included compose.yaml gives you a local Raspberry Pi OS deployment example. For ha-docker-pxe-deploy, treat it as reference material only and use the JSON container spec above instead of Compose directly.

docker compose up -d --build

Override build args or runtime settings through environment variables:

BASE_IMAGE=debian:trixie-slim LG_TAG=202603-off-fix RGPIOD_ALLOWED_IPS=192.168.1.10 docker compose up -d --build

Security note

By default rgpiod allows remote TCP clients. If the service should only be reachable locally or by a small set of clients, set either:

• RGPIOD_LOCAL_ONLY=1
• RGPIOD_ALLOWED_IPS=192.168.1.10,192.168.1.11
• RGPIOD_ACCESS_CONTROL=1

Sources

• ha-docker-pxe-deploy agent guidance for Git-backed remote builds: https://github.com/Clam-/ha-docker-pxe-deploy/blob/main/README.md
• Clam-/lg fork used by default for source builds: https://github.com/Clam-/lg
• Debian trixie-slim base image tags used by default here: https://hub.docker.com/_/debian
• Upstream rgpiod documentation and launch options: https://lg.raspberrybasic.org/rgpiod.html
• Upstream rgs client documentation: https://lg.raspberrybasic.org/rgs.html