116 lines
3.5 KiB
Markdown
116 lines
3.5 KiB
Markdown
# 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 .
|
|
```
|
|
|
|
|
|
|
|
|
|
|
|
|