ci: 👷 add support for docker image publish

amd989 · amd989 · commit 2fd13ccf863a · 2025-10-16T16:35:51.000-04:00
diff --git a/.github/workflows/docker-build.yml b/.github/workflows/docker-build.yml
@@ -0,0 +1,75 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches:
+      - master
+    paths-ignore:
+      - '**.md'
+      - 'docs/**'
+      - 'LICENSE'
+      - '.gitignore'
+  workflow_dispatch:  # Allow manual trigger
+
+env:
+  DOCKERHUB_USERNAME: amd989
+  IMAGE_NAME: amd989/xbee2mqtt
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+        with:
+          platforms: all
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@v3
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Extract metadata (tags, labels)
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.IMAGE_NAME }}
+          tags: |
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha,prefix={{branch}}-
+            type=ref,event=branch
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: ./Dockerfile
+          platforms: linux/amd64,linux/arm64,linux/arm/v7,linux/arm/v6,linux/386
+          push: true
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=registry,ref=${{ env.IMAGE_NAME }}:buildcache
+          cache-to: type=registry,ref=${{ env.IMAGE_NAME }}:buildcache,mode=max
+
+      - name: Update Docker Hub description
+        uses: peter-evans/dockerhub-description@v4
+        with:
+          username: ${{ env.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+          repository: ${{ env.IMAGE_NAME }}
+          short-description: "XBee to MQTT gateway - Python 3 daemon for bridging XBee ZigBee radios to MQTT brokers"
+          readme-filepath: ./README.md
+        continue-on-error: true
+
+      - name: Image digest
+        run: echo "Image pushed with digest ${{ steps.meta.outputs.digest }}"
diff --git a/README.md b/README.md
@@ -1,5 +1,9 @@
 # xbee2mqtt
 
+[![Docker Pulls](https://img.shields.io/docker/pulls/amd989/xbee2mqtt)](https://hub.docker.com/r/amd989/xbee2mqtt)
+[![Docker Image Size](https://img.shields.io/docker/image-size/amd989/xbee2mqtt/latest)](https://hub.docker.com/r/amd989/xbee2mqtt)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/amd989/xbee2mqtt/docker-build.yml?branch=master)](https://github.com/amd989/xbee2mqtt/actions)
+
 A Python 3 daemon that bridges XBee ZigBee radios to MQTT brokers. It monitors a coordinator XBee connected to a serial port, translates radio messages to MQTT topics, and enables remote control of XBee digital I/O pins through MQTT commands.
 
 From version 0.3 it also supports setting digital pins LOW or HIGH on remote radios.
@@ -10,7 +14,26 @@ From version 0.3 it also supports setting digital pins LOW or HIGH on remote rad
 
 ## Quick Start with Docker (Recommended)
 
-The easiest way to run xbee2mqtt is using Docker. Works on any Linux system including Raspberry Pi!
+The easiest way to run xbee2mqtt is using Docker. Pre-built images available for all major architectures!
+
+### Using Docker Hub (Recommended)
+
+```bash
+# Pull the latest image (automatically selects your architecture)
+docker pull amd989/xbee2mqtt:latest
+
+# Or use docker-compose (see docker-compose.yml)
+docker-compose up -d
+```
+
+**Supported architectures:**
+- `linux/amd64` - x86 64-bit (PCs, servers, cloud)
+- `linux/arm64` - ARM 64-bit (Raspberry Pi 3/4/5 with 64-bit OS)
+- `linux/arm/v7` - ARM 32-bit v7 (Raspberry Pi 2/3/4 with 32-bit OS)
+- `linux/arm/v6` - ARM 32-bit v6 (Raspberry Pi Zero, Pi 1)
+- `linux/386` - x86 32-bit
+
+### Quick Setup
 
 ```bash
 # 1. Copy and configure
diff --git a/docker-compose.dev.yml b/docker-compose.dev.yml
@@ -0,0 +1,43 @@
+version: '3.8'
+
+services:
+  xbee2mqtt:
+    build: .
+    container_name: xbee2mqtt-dev
+    restart: unless-stopped
+
+    # Serial device access - update to match your XBee device
+    # Common options:
+    #   USB-to-Serial adapter: /dev/ttyUSB0
+    #   Raspberry Pi GPIO UART: /dev/ttyAMA0 or /dev/serial0
+    #   Raspberry Pi USB: /dev/ttyUSB0
+    devices:
+      - /dev/ttyUSB0:/dev/ttyUSB0
+      # For Raspberry Pi GPIO UART, uncomment:
+      # - /dev/ttyAMA0:/dev/ttyAMA0
+      # - /dev/serial0:/dev/serial0
+
+    # Privileged mode for serial port access (alternative to devices)
+    # Only use if device mapping doesn't work
+    # privileged: true
+
+    volumes:
+      # Mount config directory
+      - ./config:/app/config:ro
+      # Mount var directory for logs and PID file
+      - ./var:/app/var
+
+    environment:
+      # Optional: Override logging level (10=DEBUG, 20=INFO, 30=WARNING, 40=ERROR)
+      - LOGGING_LEVEL=20
+
+    # Network mode for MQTT connectivity
+    # Use 'host' if MQTT broker is on localhost
+    # Or use 'bridge' (default) and specify broker IP in config
+    network_mode: bridge
+
+    logging:
+      driver: "json-file"
+      options:
+        max-size: "10m"
+        max-file: "3"
diff --git a/docker-compose.yml b/docker-compose.yml
@@ -2,7 +2,7 @@ version: '3.8'
 
 services:
   xbee2mqtt:
-    build: .
+    image: amd989/xbee2mqtt:latest
     container_name: xbee2mqtt
     restart: unless-stopped
 
diff --git a/docs/README.docker.md b/docs/README.docker.md
@@ -9,6 +9,45 @@ This guide explains how to run xbee2mqtt in a Docker container for consistent de
 - XBee coordinator radio connected via USB (typically `/dev/ttyUSB0`)
 - MQTT broker accessible (can be on same host or remote)
 
+## Docker Hub vs Local Build
+
+There are two ways to run xbee2mqtt with Docker:
+
+### Option 1: Docker Hub (Recommended)
+
+Pull pre-built multi-architecture images from Docker Hub:
+
+```bash
+docker pull amd989/xbee2mqtt:latest
+```
+
+**Advantages:**
+- ✅ No build time - instant deployment
+- ✅ Automatically selects correct architecture (amd64, arm64, arm/v7, arm/v6, 386)
+- ✅ Always up-to-date with latest stable release
+- ✅ Verified builds from CI/CD pipeline
+
+**Use this if:** You want to run the stable version without modifying code.
+
+The default `docker-compose.yml` uses Docker Hub images.
+
+### Option 2: Local Build
+
+Build the Docker image locally from source:
+
+```bash
+docker-compose -f docker-compose.dev.yml up --build
+```
+
+**Advantages:**
+- ✅ Test local code changes
+- ✅ Development and debugging
+- ✅ Custom modifications
+
+**Use this if:** You're developing or need to modify the code.
+
+The `docker-compose.dev.yml` file is configured for local builds.
+
 ## Quick Start
 
 ### 1. Configure the Application
@@ -51,6 +90,7 @@ Update `docker-compose.yml` with your device path. The default is `/dev/ttyUSB0`
 
 ### 3. Start with Docker Compose
 
+**Using Docker Hub image (recommended):**
 ```bash
 # Start in background
 docker-compose up -d
@@ -62,37 +102,63 @@ docker-compose logs -f
 docker-compose down
 ```
 
+**Using local build (for development):**
+```bash
+# Build and start
+docker-compose -f docker-compose.dev.yml up -d
+
+# View logs
+docker-compose -f docker-compose.dev.yml logs -f
+
+# Stop
+docker-compose -f docker-compose.dev.yml down
+```
+
 ## Manual Docker Commands
 
 If you prefer not to use Docker Compose:
 
-### Build the Image
+### Using Docker Hub Image
 
 ```bash
-docker build -t xbee2mqtt .
+# Pull the image
+docker pull amd989/xbee2mqtt:latest
+
+# Run the container
+docker run -d \
+  --name xbee2mqtt \
+  --restart unless-stopped \
+  --device=/dev/ttyUSB0:/dev/ttyUSB0 \
+  -v $(pwd)/config:/app/config:ro \
+  -v $(pwd)/var:/app/var \
+  amd989/xbee2mqtt:latest
 ```
 
-### Run the Container
+### Local Build
 
 ```bash
+# Build the image
+docker build -t xbee2mqtt-local .
+
+# Run the container
 docker run -d \
   --name xbee2mqtt \
   --restart unless-stopped \
   --device=/dev/ttyUSB0:/dev/ttyUSB0 \
   -v $(pwd)/config:/app/config:ro \
   -v $(pwd)/var:/app/var \
-  xbee2mqtt
+  xbee2mqtt-local
 ```
 
-**Windows (PowerShell):**
+**Windows (PowerShell) with Docker Hub:**
 ```powershell
 docker run -d `
   --name xbee2mqtt `
   --restart unless-stopped `
   --device=/dev/ttyUSB0:/dev/ttyUSB0 `
   -v ${PWD}/config:/app/config:ro `
   -v ${PWD}/var:/app/var `
-  xbee2mqtt
+  amd989/xbee2mqtt:latest
 ```
 
 ### Manage the Container
@@ -289,7 +355,7 @@ services:
       - ./mosquitto/data:/mosquitto/data
 
   xbee2mqtt:
-    build: .
+    image: amd989/xbee2mqtt:latest
     container_name: xbee2mqtt
     restart: unless-stopped
     depends_on:
@@ -303,6 +369,8 @@ services:
 
 Set MQTT host to `mosquitto` in your config file.
 
+**For local development**, use `build: .` instead of `image: amd989/xbee2mqtt:latest`.
+
 ## Testing the Migration
 
 After the Python 2 to Python 3 migration, you should verify everything works:
@@ -409,14 +477,31 @@ If you encounter Python errors:
 
 ## Updating
 
-To update to a new version:
+### Updating Docker Hub Image
+
+To update to the latest version from Docker Hub:
+
+```bash
+# Pull latest image
+docker pull amd989/xbee2mqtt:latest
+
+# Restart with new image
+docker-compose down
+docker-compose up -d
+```
+
+The latest image is automatically built from the master branch via GitHub Actions.
+
+### Updating Local Build
+
+To update with local changes:
 
 ```bash
 # Pull latest code
 git pull
 
 # Rebuild and restart
-docker-compose down
-docker-compose build --no-cache
-docker-compose up -d
+docker-compose -f docker-compose.dev.yml down
+docker-compose -f docker-compose.dev.yml build --no-cache
+docker-compose -f docker-compose.dev.yml up -d
 ```
