# 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