intermediate commit

2025-11-17 21:56:21 +01:00
parent b516c942df
commit d72ee4a7d2
8 changed files with 667 additions and 13 deletions
@@ -0,0 +1,112 @@
+# Docker Webhook Updater
+
+A Docker container that monitors a Docker image for updates and triggers a webhook when a new version is detected.
+
+## Features
+
+- Monitors Docker images from any registry (Docker Hub, GHCR, Quay.io, custom registries)
+- Detects image updates by comparing SHA256 digests
+- Triggers webhook with bearer token authentication
+- Persistent SHA storage across container restarts
+- Configurable check interval
+
+## Environment Variables
+
+| Variable          | Description                             | Required | Example                                               |
+| ----------------- | --------------------------------------- | -------- | ----------------------------------------------------- |
+| `DOCKER_REPO_URL` | Docker registry URL                     | Yes      | `docker.io`, `ghcr.io`, `quay.io`, or custom registry |
+| `DOCKER_IMAGE`    | Full image name with tag                | Yes      | `username/image:latest`, `library/nginx:1.25`         |
+| `WEBHOOK_URL`     | URL to call when image is updated       | Yes      | `https://example.com/webhook`                         |
+| `WEBHOOK_TOKEN`   | Bearer token for webhook authentication | Yes      | `your-secret-token`                                   |
+| `CHECK_INTERVAL`  | Seconds between checks (default: 300)   | No       | `600`                                                 |
+
+## Usage
+
+### Docker Hub Example
+
+```bash
+docker run -d \
+  -e DOCKER_REPO_URL=docker.io \
+  -e DOCKER_IMAGE=library/nginx:latest \
+  -e WEBHOOK_URL=https://example.com/webhook \
+  -e WEBHOOK_TOKEN=your-secret-token \
+  -e CHECK_INTERVAL=300 \
+  your-registry/docker-webhook-updater:latest
+```
+
+### GitHub Container Registry Example
+
+```bash
+docker run -d \
+  -e DOCKER_REPO_URL=ghcr.io \
+  -e DOCKER_IMAGE=username/repo:latest \
+  -e WEBHOOK_URL=https://example.com/webhook \
+  -e WEBHOOK_TOKEN=your-secret-token \
+  your-registry/docker-webhook-updater:latest
+```
+
+### Docker Compose Example
+
+```yaml
+version: "3.8"
+
+services:
+  webhook-updater:
+    image: your-registry/docker-webhook-updater:latest
+    environment:
+      - DOCKER_REPO_URL=docker.io
+      - DOCKER_IMAGE=library/nginx:latest
+      - WEBHOOK_URL=https://example.com/webhook
+      - WEBHOOK_TOKEN=your-secret-token
+      - CHECK_INTERVAL=300
+    restart: unless-stopped
+```
+
+## How It Works
+
+1. The service periodically checks the Docker registry for the specified image
+2. It retrieves the SHA256 digest of the image manifest
+3. Compares the current SHA with the previously stored SHA
+4. If different, triggers the webhook with a POST request containing:
+   ```json
+   {
+     "event": "image_updated",
+     "image": "username/image:latest",
+     "repo_url": "docker.io"
+   }
+   ```
+5. Updates the stored SHA only after successful webhook trigger
+
+## Webhook Request Format
+
+When an image update is detected, the service sends a POST request to the webhook URL:
+
+- **Method**: POST
+- **Headers**:
+  - `Authorization: Bearer {WEBHOOK_TOKEN}`
+  - `Content-Type: application/json`
+- **Body**:
+  ```json
+  {
+    "event": "image_updated",
+    "image": "username/image:tag",
+    "repo_url": "docker.io"
+  }
+  ```
+
+## Notes
+
+- The SHA is stored in `/app/sha.txt` inside the container
+- On first run, the SHA is stored without triggering the webhook
+- If the webhook fails, the SHA is not updated, so it will retry on the next check
+- For private Docker images, authentication may be required (not currently supported)
+- The service runs continuously and checks at the specified interval
+
+## Building
+
+```bash
+docker build -t docker-webhook-updater:latest .
+```
+
+
+