Sanitized mirror from private repository - 2026-04-20 01:32:01 UTC

docs/guides/diun-image-notifications.md

@@ -0,0 +1,107 @@
+# Diun — Docker Image Update Notifications
+
+Diun (Docker Image Update Notifier) watches all containers on a host and sends an ntfy notification when an upstream image's digest changes — meaning a new version has been published.
+
+Notifications arrive at: `https://ntfy.vish.gg/diun`
+
+Schedule: **Mondays at 09:00** (weekly check, 30s random jitter to spread load).
+
+---
+
+## Hosts
+
+| Host | Compose file |
+|------|-------------|
+| homelab-vm | `hosts/vms/homelab-vm/diun.yaml` |
+| atlantis | `hosts/synology/atlantis/diun.yaml` |
+| calypso | `hosts/synology/calypso/diun.yaml` |
+| setillo | `hosts/synology/setillo/diun.yaml` |
+| concord-nuc | `hosts/physical/concord-nuc/diun.yaml` |
+| pi-5 | `hosts/edge/rpi5-vish/diun.yaml` |
+| seattle | `hosts/vms/seattle/diun.yaml` |
+| matrix-ubuntu | `hosts/vms/matrix-ubuntu-vm/diun.yaml` |
+
+---
+
+## Deployment
+
+### Portainer GitOps (Synology + homelab-vm)
+
+For each Synology host and homelab-vm, add a Portainer stack pointing to the compose file in this repo.
+
+### Portainer Edge Agents (concord-nuc, pi-5)
+
+Deploy via the appropriate edge endpoint in Portainer.
+
+### SSH deploy (seattle, matrix-ubuntu)
+
+```bash
+# Copy compose to host and bring up
+scp hosts/vms/seattle/diun.yaml seattle:/home/vish/diun.yaml
+ssh seattle "docker compose -f /home/vish/diun.yaml up -d"
+
+scp hosts/vms/matrix-ubuntu-vm/diun.yaml matrix-ubuntu:/home/test/diun.yaml
+ssh matrix-ubuntu "docker compose -f /home/test/diun.yaml up -d"
+```
+
+### Setillo (root SSH required)
+
+```bash
+ssh setillo-root
+# Copy file to setillo first, then:
+docker compose -f /root/diun.yaml up -d
+```
+
+---
+
+## Validation
+
+```bash
+# List all watched images and their current digest
+docker exec diun diun image list
+
+# Trigger an immediate check (without waiting for Monday)
+docker exec diun diun image check
+
+# Check logs
+docker logs diun --tail 30
+```
+
+Expected log on startup:
+```
+time="..." level=info msg="Starting Diun..."
+time="..." level=info msg="Found 12 image(s) to watch"
+```
+
+Expected ntfy notification when an image updates:
+```
+Title: [diun] Update found for image ...
+Body:  docker.io/amir20/dozzle:latest (...)
+```
+
+---
+
+## Per-image Opt-out
+
+To exclude a specific container from Diun watching, add a label to its compose service:
+
+```yaml
+services:
+  myservice:
+    labels:
+      - "diun.enable=false"
+```
+
+---
+
+## Troubleshooting
+
+**No notifications received**
+→ Verify ntfy is reachable from the container: `docker exec diun wget -q -O /dev/null https://ntfy.vish.gg/diun`
+→ Check `DIUN_NOTIF_NTFY_ENDPOINT` and `DIUN_NOTIF_NTFY_TOPIC` env vars
+
+**"permission denied" on docker.sock (Synology)**
+→ Run the container via Portainer (which runs as root) rather than the `vish` user directly
+
+**Diun watches too many images (registry rate limits)**
+→ Reduce `DIUN_WATCH_WORKERS` or set `DIUN_PROVIDERS_DOCKER_WATCHBYDEFAULT: "false"` and opt-in with `diun.enable=true` labels