Merge branch 'review/pr-847'

.dockerignore

@@ -0,0 +1,10 @@
+*
+!Containerfile*
+!Dockerfile
+!README.md
+!bin/container-entrypoint.sh
+!examples/
+!extra/
+!meshtastic/
+!poetry.lock
+!pyproject.toml

.github/workflows/container-build.yaml

@@ -0,0 +1,77 @@
+name: Create and publish Container image
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - '*.*.*'
+  pull_request:
+    branches:
+      - master
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push-image:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    strategy:
+      matrix:
+        include:
+          - container: Containerfile.debian
+            autotag: false
+            suffix: -debian
+          - container: Containerfile.alpine
+            autotag: ${{ github.ref == 'refs/heads/master' && 'true' || 'auto' }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Login to Container registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=edge
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+          flavor: |
+            latest=${{ matrix.autotag }}
+            suffix=${{ matrix.suffix }}
+
+      - name: Build and push
+        uses: docker/build-push-action@v6
+        with:
+          platforms: linux/amd64,linux/arm64,linux/arm/v7
+          context: .
+          file: ${{ matrix.container }}
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}

Containerfile

@@ -0,0 +1 @@
+Containerfile.alpine

Containerfile.alpine

@@ -0,0 +1,30 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Copyright (C) 2025 Olliver Schinagl <oliver@schinagl.nl>
+
+ARG TARGET_VERSION="3.11-alpine"
+ARG TARGET_ARCH="library"
+
+FROM docker.io/${TARGET_ARCH}/python:${TARGET_VERSION}
+
+WORKDIR /tmp/build
+
+COPY . /tmp/build
+
+RUN _poetry_venv_dir="$(mktemp -d -p "${TMPDIR:-/tmp}" 'poetry_venv.XXXXXX')" && \
+    python -m 'venv' "${_poetry_venv_dir}" && \
+    "${_poetry_venv_dir}/bin/pip" install --no-cache-dir 'poetry' && \
+    "${_poetry_venv_dir}/bin/poetry" config --local virtualenvs.create false && \
+    "${_poetry_venv_dir}/bin/poetry" install --without dev --extras cli --extras tunnel --no-interaction --no-ansi && \
+    addgroup -S meshtastic && \
+    adduser -S -G meshtastic -h /home/meshtastic meshtastic && \
+    rm -f -r "${_poetry_venv_dir}" && \
+    rm -f -r "/tmp/build"
+
+COPY "./bin/container-entrypoint.sh" "/init"
+RUN chmod 0755 /init
+
+WORKDIR /home/meshtastic
+USER meshtastic
+
+ENTRYPOINT [ "/init" ]

Containerfile.debian

@@ -0,0 +1,29 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Copyright (C) 2025 Olliver Schinagl <oliver@schinagl.nl>
+
+ARG TARGET_VERSION="3.11"
+ARG TARGET_ARCH="library"
+
+FROM docker.io/${TARGET_ARCH}/python:${TARGET_VERSION}
+
+WORKDIR /tmp/build
+
+COPY . /tmp/build
+
+RUN _poetry_venv_dir="$(mktemp -d -p "${TMPDIR:-/tmp}" 'poetry_venv.XXXXXX')" && \
+    python -m 'venv' "${_poetry_venv_dir}" && \
+    "${_poetry_venv_dir}/bin/pip" install --no-cache-dir 'poetry' && \
+    "${_poetry_venv_dir}/bin/poetry" config --local virtualenvs.create false && \
+    "${_poetry_venv_dir}/bin/poetry" install --without dev --extras cli --extras tunnel --no-interaction --no-ansi && \
+    useradd --system --create-home --home-dir /home/meshtastic meshtastic && \
+    rm -f -r "${_poetry_venv_dir}" && \
+    rm -f -r "/tmp/build"
+
+COPY "./bin/container-entrypoint.sh" "/init"
+RUN chmod 0755 /init
+
+WORKDIR /home/meshtastic
+USER meshtastic
+
+ENTRYPOINT [ "/init" ]

Dockerfile

@@ -0,0 +1 @@
+Containerfile

README.md

@@ -27,6 +27,24 @@ This small library (and example application) provides an easy API for sending an
 It also provides access to any of the operations/data available in the device user interface or the Android application.
 Events are delivered using a publish-subscribe model, and you can subscribe to only the message types you are interested in.
 
+## Container usage
+
+Container images are published to GHCR for this repository. The container entrypoint defaults to running `meshtastic`,
+so CLI flags can be passed directly:
+
+```bash
+docker run --rm ghcr.io/meshtastic/python --help
+```
+
+To run another command, pass it explicitly (for example, a shell):
+
+```bash
+docker run --rm -it --entrypoint /bin/sh ghcr.io/meshtastic/python
+```
+
+The container runs as a non-root user by default. When talking to local hardware, pass the serial device through
+explicitly (for example `--device /dev/ttyUSB0:/dev/ttyUSB0`) and ensure host device permissions allow access.
+
 ## Call for Contributors
 
 This library and CLI has gone without a consistent maintainer for a while, and there's many improvements that could be made. We're all volunteers here and help is extremely appreciated, whether in implementing your own needs or helping maintain the library and CLI in general.

bin/container-entrypoint.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# Copyright (C) 2025 Olliver Schinagl <oliver@schinagl.nl>
+#
+# A beginning user should be able to docker run image bash (or sh) without
+# needing to learn about --entrypoint
+# https://github.com/docker-library/official-images#consistency
+
+set -eu
+
+bin='meshtastic'
+
+# run command if it is not starting with a "-" and is an executable in PATH
+if [ "${#}" -le 0 ] || \
+   [ "${1#-}" != "${1}" ] || \
+   [ -d "${1}" ] || \
+   ! command -v "${1}" > '/dev/null' 2>&1; then
+	entrypoint='true'
+fi
+
+exec ${entrypoint:+${bin:?}} "${@}"
+
+exit 0