Einfuehrung

Bei matzka.cloud betreiben wir ueber 45 Docker-Container in 8 verschiedenen Stacks. Die manuelle Aktualisierung dieser Container war zeitaufwendig und fehleranfaellig. Das neue Auto-Update-System automatisiert diesen Prozess vollstaendig und informiert uns proaktiv ueber verfuegbare Updates.

Das neue System basiert auf vier Kernkomponenten, die zusammenarbeiten um automatische Updates, Benachrichtigungen und manuelles Management zu ermoeglichen.

Architektur

Update-Zeitplan

Systemarchitektur

Die vier Komponenten

Watchtower - Automatische Container Updates

Funktionsweise

1. Watchtower prueft regelmaessig (Sonntag 04:00 UTC) alle Container mit dem Label com.centurylinklabs.watchtower.enable=true
2. Fuer jeden Container wird geprueft, ob ein neueres Image in der Registry verfuegbar ist
3. Bei Updates: Pull neues Image, stoppe Container, starte mit neuem Image
4. Cleanup: Alte, nicht mehr verwendete Images werden automatisch geloescht
5. Benachrichtigung via E-Mail und Gotify

Konfiguration

watchtower:
  image: containrrr/watchtower:1.7.1
  container_name: watchtower
  restart: unless-stopped
  networks:
    - updates
    - smtp-internal
  environment:
    # Docker API Version (erforderlich fuer Docker 29+)
    DOCKER_API_VERSION: "1.44"

    # Schedule: Jeden Sonntag um 04:00 UTC
    WATCHTOWER_SCHEDULE: "0 0 4 * * 0"

    # Nur Container mit Label updaten (opt-in)
    WATCHTOWER_LABEL_ENABLE: "true"

    # Alte Images nach Update loeschen
    WATCHTOWER_CLEANUP: "true"

    # Timeout fuer Container-Stop
    WATCHTOWER_TIMEOUT: "60s"

    # Lifecycle Hooks aktivieren
    WATCHTOWER_LIFECYCLE_HOOKS: "true"

    # Monitor-Only Modus (false = echte Updates)
    WATCHTOWER_MONITOR_ONLY: "${WATCHTOWER_MONITOR_ONLY:-false}"

    # Multi-Channel Benachrichtigungen
    WATCHTOWER_NOTIFICATIONS: "shoutrrr"
    WATCHTOWER_NOTIFICATION_URL: "smtp://smtp-relay:25/?from=watchtower@matzka.cloud&to=reinhard@matzka.cloud&subject=Watchtower+Update&auth=None&useStartTLS=No gotify://gotify:80/${GOTIFY_APP_TOKEN}?priority=5&disableTLS=yes"

    TZ: Europe/Vienna
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - /etc/localtime:/etc/localtime:ro

Diun - Docker Image Update Notifier

Funktionsweise

1. Diun prueft alle 6 Stunden Container mit dem Label diun.enable=true
2. Vergleicht lokale Image-Digests mit Registry-Digests
3. Bei neuer Version: Benachrichtigung via E-Mail
4. Speichert Status in lokaler SQLite-Datenbank

Konfiguration (diun.yml)

# /opt/docker/updates/diun/diun.yml
db:
  path: /data/diun.db

watch:
  schedule: "0 */6 * * *"    # Alle 6 Stunden
  firstCheckNotif: false      # Keine Benachrichtigung beim ersten Check
  compareDigest: true         # Digest-basierter Vergleich

defaults:
  notifyOn:
    - new                     # Neue Tags
    - update                  # Aktualisierte Digests

providers:
  docker:
    watchByDefault: false     # Nur gelabelte Container

notif:
  mail:
    host: smtp-relay
    port: 25
    ssl: false
    localName: diun.matzka.cloud
    from: diun@matzka.cloud
    to:
      - reinhard@matzka.cloud

Dockge - Container Management Web UI

Features

• Realtime Container-Status und Logs
• Docker Compose YAML Editor mit Syntax-Highlighting
• Stack-Verwaltung (Start, Stop, Restart, Down, Up)
• Multi-Stack Uebersicht
• Authentik SSO Integration (nur admins Gruppe)

Konfiguration

dockge:
  image: louislam/dockge:1
  container_name: dockge
  restart: unless-stopped
  networks:
    - frontend
    - updates
  environment:
    DOCKGE_PORT: 5001
    DOCKGE_STACKS_DIR: /opt/stacks
    TZ: Europe/Vienna
  volumes:
    - /var/run/docker.sock:/var/run/docker.sock:ro
    - dockge_data:/app/data
    # Stack-Verzeichnisse einbinden
    - /opt/docker/compose:/opt/stacks/compose
    - /opt/docker/webapp:/opt/stacks/webapp
    - /opt/docker/n8n:/opt/stacks/n8n
    - /opt/docker/monitoring:/opt/stacks/monitoring
    - /opt/docker/security:/opt/stacks/security
    - /opt/docker/gitea:/opt/stacks/gitea
    - /opt/docker/updates:/opt/stacks/updates
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.dockge.rule=Host(`dockge.${DOMAIN}`)"
    - "traefik.http.routers.dockge.entrypoints=websecure"
    - "traefik.http.routers.dockge.tls.certresolver=letsencrypt"
    - "traefik.http.services.dockge.loadbalancer.server.port=5001"
    - "traefik.http.routers.dockge.middlewares=dockge-auth@file"
    - "traefik.docker.network=frontend"

Traefik Middleware fuer Authentik SSO

# /opt/docker/compose/traefik/dynamic/updates.yml
http:
  middlewares:
    dockge-auth:
      forwardAuth:
        address: "http://authentik-server:9000/outpost.goauthentik.io/auth/traefik"
        trustForwardHeader: true
        authResponseHeaders:
          - X-authentik-username
          - X-authentik-groups
          - X-authentik-email
          - X-authentik-name
          - X-authentik-uid

Gotify - Self-Hosted Push Notifications

Features

• WebSocket-basierte Echtzeit-Notifications
• Android App verfuegbar (F-Droid, Play Store)
• REST API fuer Integration mit anderen Tools
• Application Tokens fuer sichere Authentifizierung
• Priority-Levels fuer unterschiedliche Wichtigkeit

Konfiguration

gotify:
  image: gotify/server:latest
  container_name: gotify
  restart: unless-stopped
  networks:
    - frontend
    - updates
  environment:
    TZ: Europe/Vienna
    GOTIFY_DEFAULTUSER_NAME: ${GOTIFY_ADMIN_USER:-admin}
    GOTIFY_DEFAULTUSER_PASS: ${GOTIFY_ADMIN_PASSWORD}
  volumes:
    - gotify_data:/app/data
  healthcheck:
    test: ["CMD-SHELL", "curl -sf http://localhost:80/health || exit 1"]
    interval: 30s
    timeout: 10s
    retries: 3
  labels:
    - "traefik.enable=true"
    - "traefik.http.routers.gotify.rule=Host(`gotify.${DOMAIN}`)"
    - "traefik.http.routers.gotify.entrypoints=websecure"
    - "traefik.http.routers.gotify.tls.certresolver=letsencrypt"
    - "traefik.http.services.gotify.loadbalancer.server.port=80"
    - "traefik.docker.network=frontend"

Application Token erstellen

1. Oeffne https://gotify.matzka.cloud und melde dich an
2. Gehe zu "Apps" im linken Menue
3. Klicke "Create Application"
4. Name: "Watchtower" (oder "Diun")
5. Kopiere das generierte Token
6. Trage das Token in die .env Datei ein

Vollstaendige Konfiguration

docker-compose.yml

# /opt/docker/updates/docker-compose.yml

services:
  watchtower:
    image: containrrr/watchtower:1.7.1
    container_name: watchtower
    restart: unless-stopped
    networks:
      - updates
      - smtp-internal
    environment:
      DOCKER_API_VERSION: "1.44"
      WATCHTOWER_SCHEDULE: "0 0 4 * * 0"
      WATCHTOWER_LABEL_ENABLE: "true"
      WATCHTOWER_CLEANUP: "true"
      WATCHTOWER_TIMEOUT: "60s"
      WATCHTOWER_INCLUDE_STOPPED: "false"
      WATCHTOWER_INCLUDE_RESTARTING: "true"
      WATCHTOWER_LIFECYCLE_HOOKS: "true"
      WATCHTOWER_MONITOR_ONLY: "${WATCHTOWER_MONITOR_ONLY:-false}"
      WATCHTOWER_NOTIFICATIONS: "shoutrrr"
      WATCHTOWER_NOTIFICATION_URL: "smtp://smtp-relay:25/?from=watchtower@matzka.cloud&to=reinhard@matzka.cloud&subject=Watchtower+Update&auth=None&useStartTLS=No gotify://gotify:80/${GOTIFY_APP_TOKEN}?priority=5&disableTLS=yes"
      TZ: Europe/Vienna
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - /etc/localtime:/etc/localtime:ro
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
      - "diun.enable=false"

  diun:
    image: crazymax/diun:latest
    container_name: diun
    restart: unless-stopped
    networks:
      - updates
      - smtp-internal
    environment:
      TZ: Europe/Vienna
      LOG_LEVEL: info
      LOG_JSON: "false"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - diun_data:/data
      - ./diun/diun.yml:/diun.yml:ro
    healthcheck:
      test: ["CMD", "diun", "--version"]
      interval: 60s
      timeout: 10s
      retries: 3
    labels:
      - "com.centurylinklabs.watchtower.enable=false"
      - "diun.enable=false"

  dockge:
    image: louislam/dockge:1
    container_name: dockge
    restart: unless-stopped
    networks:
      - frontend
      - updates
    environment:
      DOCKGE_PORT: 5001
      DOCKGE_STACKS_DIR: /opt/stacks
      TZ: Europe/Vienna
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - dockge_data:/app/data
      - /opt/docker/compose:/opt/stacks/compose
      - /opt/docker/webapp:/opt/stacks/webapp
      - /opt/docker/n8n:/opt/stacks/n8n
      - /opt/docker/monitoring:/opt/stacks/monitoring
      - /opt/docker/security:/opt/stacks/security
      - /opt/docker/gitea:/opt/stacks/gitea
      - /opt/docker/updates:/opt/stacks/updates
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.dockge.rule=Host(`dockge.${DOMAIN}`)"
      - "traefik.http.routers.dockge.entrypoints=websecure"
      - "traefik.http.routers.dockge.tls.certresolver=letsencrypt"
      - "traefik.http.services.dockge.loadbalancer.server.port=5001"
      - "traefik.http.routers.dockge.middlewares=dockge-auth@file"
      - "traefik.docker.network=frontend"
      - "com.centurylinklabs.watchtower.enable=false"
      - "diun.enable=true"
      - "diun.watch_repo=true"

  gotify:
    image: gotify/server:latest
    container_name: gotify
    restart: unless-stopped
    networks:
      - frontend
      - updates
    environment:
      TZ: Europe/Vienna
      GOTIFY_DEFAULTUSER_NAME: ${GOTIFY_ADMIN_USER:-admin}
      GOTIFY_DEFAULTUSER_PASS: ${GOTIFY_ADMIN_PASSWORD}
    volumes:
      - gotify_data:/app/data
    healthcheck:
      test: ["CMD-SHELL", "curl -sf http://localhost:80/health || exit 1"]
      interval: 30s
      timeout: 10s
      retries: 3
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.gotify.rule=Host(`gotify.${DOMAIN}`)"
      - "traefik.http.routers.gotify.entrypoints=websecure"
      - "traefik.http.routers.gotify.tls.certresolver=letsencrypt"
      - "traefik.http.services.gotify.loadbalancer.server.port=80"
      - "traefik.docker.network=frontend"
      - "com.centurylinklabs.watchtower.enable=true"
      - "diun.enable=true"

networks:
  frontend:
    external: true
    name: frontend

  smtp-internal:
    external: true
    name: smtp-internal

  updates:
    name: updates
    driver: bridge

volumes:
  diun_data:
    name: diun_data

  dockge_data:
    name: dockge_data

  gotify_data:
    name: gotify_data

.env Datei

# /opt/docker/updates/.env

# Domain
DOMAIN=matzka.cloud

# Watchtower Settings
WATCHTOWER_MONITOR_ONLY=false

# Gotify Credentials
GOTIFY_ADMIN_USER=admin
GOTIFY_ADMIN_PASSWORD=<sicheres_passwort>
GOTIFY_APP_TOKEN=<watchtower_app_token>

Container Labels

Das Update-System verwendet ein Opt-in Modell. Nur Container mit den entsprechenden Labels werden von Watchtower aktualisiert bzw. von Diun ueberwacht.

Watchtower Labels

Diun Labels

Beispiel: Service mit Abhaengigkeit

# Gitea haengt von PostgreSQL ab
postgres-gitea:
  image: postgres:17-alpine
  labels:
    - "com.centurylinklabs.watchtower.enable=true"
    - "diun.enable=true"
    - "diun.watch_repo=true"

gitea:
  image: gitea/gitea:1.22-rootless
  depends_on:
    postgres-gitea:
      condition: service_healthy
  labels:
    - "com.centurylinklabs.watchtower.enable=true"
    - "com.centurylinklabs.watchtower.depends-on=postgres-gitea"
    - "diun.enable=true"
    - "diun.watch_repo=true"

Update-Status aller Container

Benachrichtigungen

Multi-Channel Notification System

Das System verwendet Shoutrrr fuer flexible Multi-Channel Benachrichtigungen. Aktuell sind zwei Kanaele konfiguriert:

1. E-Mail via SMTP-Relay

smtp://smtp-relay:25/?from=watchtower@matzka.cloud&to=reinhard@matzka.cloud&subject=Watchtower+Update&auth=None&useStartTLS=No

• Verwendet internen SMTP-Relay Container
• Keine Authentifizierung erforderlich (internes Netzwerk)
• StartTLS deaktiviert (lokale Kommunikation)
• Relay leitet an Mailcow weiter

2. Gotify Push Notifications

gotify://gotify:80/${GOTIFY_APP_TOKEN}?priority=5&disableTLS=yes

• Direkte Kommunikation zum Gotify Container
• TLS deaktiviert (internes Docker Netzwerk)
• Priority 5 (Normal) - kann bei kritischen Updates erhoeht werden

Beispiel-Benachrichtigungen

Subject: Watchtower Update

Updates sind verfuegbar:
- grafana/grafana: latest -> sha256:abc123
- redis:7-alpine: latest -> sha256:def456

8 Container gescannt, 2 aktualisiert, 0 fehlgeschlagen

Subject: [Diun] New image found

Image: postgres:17-alpine
Current: sha256:abc123...
New: sha256:xyz789...
Platform: linux/amd64

Registry: docker.io
Container: postgres-nextcloud

Troubleshooting

Problem 1: Watchtower "client version is too old"

Error response from daemon: client version 1.25 is too old. Minimum supported API version is 1.44

Ursache

Docker 29+ erfordert eine neuere API-Version als Watchtower standardmaessig verwendet.

Loesung

environment:
  DOCKER_API_VERSION: "1.44"

Problem 2: Watchtower "Rolling restarts not compatible"

Rolling restarts is not compatible with the global monitor only flag

Ursache

WATCHTOWER_ROLLING_RESTART ist nicht mit WATCHTOWER_MONITOR_ONLY kompatibel.

Loesung

Entferne WATCHTOWER_ROLLING_RESTART wenn MONITOR_ONLY aktiv ist, oder deaktiviere MONITOR_ONLY fuer echte Updates.

Problem 3: Diun "field not found: templateTitle"

field not found, node: templateTitle

Ursache

Diun v4.31+ hat Konfigurationsfelder geaendert/entfernt.

Loesung

Entferne veraltete Felder aus diun.yml: templateTitle, templateBody, timeout, watchStopped

Problem 4: Health Check failed (wget not found)

OCI runtime exec failed: exec failed: unable to start container process: exec: "wget": executable file not found

Ursache

Manche Container haben wget nicht installiert.

Loesung

healthcheck:
  test: ["CMD-SHELL", "curl -sf http://localhost:PORT || exit 1"]

Problem 5: SMTP Authentication Error

smtp: 530 Must issue a STARTTLS command first

Ursache

Interner SMTP-Relay erwartet keine TLS-Verschluesselung.

Loesung

smtp://smtp-relay:25/?...&auth=None&useStartTLS=No

Problem 6: Gotify URL mit HTTPS intern

x509: certificate signed by unknown authority

Ursache

Interne Kommunikation verwendet kein TLS, aber Shoutrrr versucht HTTPS.

Loesung

gotify://gotify:80/TOKEN?disableTLS=yes

Bedienungsanleitung

1. Stack starten

cd /opt/docker/updates
docker compose up -d

2. Status pruefen

# Alle Container Status
docker compose ps

# Watchtower Logs
docker logs -f watchtower

# Diun Logs
docker logs -f diun

3. Watchtower manuell ausfuehren

# Einmaliger Update-Check (ohne tatsaechliche Updates)
docker exec watchtower /watchtower --run-once --debug

# Einmaliger Update-Check MIT Updates
docker exec watchtower /watchtower --run-once

4. Monitor-Only Modus wechseln

# In .env aendern:
WATCHTOWER_MONITOR_ONLY=true   # Nur benachrichtigen
WATCHTOWER_MONITOR_ONLY=false  # Echte Updates

# Dann Watchtower neustarten:
docker compose restart watchtower

5. Neue Container fuer Updates aktivieren

Fuege folgende Labels zur docker-compose.yml des Containers hinzu:

labels:
  # Watchtower: Automatische Updates aktivieren
  - "com.centurylinklabs.watchtower.enable=true"
  # Optional: Abhaengigkeit definieren
  - "com.centurylinklabs.watchtower.depends-on=postgres-myservice"
  # Diun: Ueberwachung aktivieren
  - "diun.enable=true"
  - "diun.watch_repo=true"

Dann Container neu erstellen:

docker compose up -d --force-recreate my-container

6. Dockge Web UI verwenden

1. Oeffne https://dockge.matzka.cloud
2. Melde dich mit Authentik SSO an (admins Gruppe erforderlich)
3. Waehle einen Stack aus der linken Seitenleiste
4. Verwende die Buttons oben rechts:
   • Start - Stack starten
   • Stop - Alle Container stoppen
   • Restart - Container neustarten
   • Update - docker compose pull und up
   • Down - Stack komplett herunterfahren

7. Gotify App einrichten

1. Installiere Gotify App (Android: F-Droid oder Play Store)
2. Oeffne die App und gehe zu Einstellungen
3. Server URL: https://gotify.matzka.cloud
4. Username: admin
5. Password: (dein Gotify Admin Passwort)
6. Push-Benachrichtigungen werden automatisch empfangen

8. Backup vor Updates

Das System ist so konfiguriert, dass Backups immer VOR Updates laufen:

• 03:00 UTC - Taegliches Backup aller Volumes
• 04:00 UTC (Sonntag) - Watchtower Updates

Bei Problemen nach einem Update kann auf das Backup zurueckgegriffen werden.

9. Rollback nach fehlgeschlagenem Update

# 1. Container stoppen
docker stop my-container

# 2. Altes Image wiederherstellen (wenn noch vorhanden)
docker image ls | grep my-image
docker run -d --name my-container my-image:old-tag

# 3. Oder aus Backup wiederherstellen
# Backup-Verzeichnis: /opt/docker/backups/
ls -la /opt/docker/backups/

# 4. Volume aus Backup extrahieren
# Siehe Backup-Dokumentation fuer Details

10. Debugging

# Watchtower Debug-Modus
docker logs watchtower 2>&1 | tail -100

# Diun Debug-Modus
docker exec diun diun --debug serve

# Notification-Test (Gotify)
curl -X POST "https://gotify.matzka.cloud/message?token=APP_TOKEN" \
  -F "title=Test" \
  -F "message=Test Nachricht" \
  -F "priority=5"

# Container Labels pruefen
docker inspect my-container | jq '.[0].Config.Labels'

Lessons Learned

Technische Erkenntnisse

1. Docker API Versionen beachten

• Docker 29+ erfordert explizite API-Version in Clients
• Immer DOCKER_API_VERSION setzen fuer Kompatibilitaet
• Watchtower :latest kann breaking changes haben - fixe Version verwenden

2. Opt-in ist besser als Opt-out

• WATCHTOWER_LABEL_ENABLE=true verhindert ungewollte Updates
• Custom Builds und kritische Services explizit ausschliessen
• Jeder Container bekommt explizite Labels

3. Interne Netzwerk-Kommunikation

• TLS zwischen Containern im selben Netzwerk ist unnoetig
• SMTP-Relay ohne Auth fuer interne Dienste
• Gotify disableTLS fuer Container-zu-Container

4. Health Checks standardisieren

• curl ist zuverlaessiger als wget (mehr Container haben es)
• CMD-SHELL fuer komplexere Checks verwenden
• Angemessene Timeouts und Retries setzen

Best Practices

Fazit

Das Docker Auto-Update System fuer matzka.cloud ist nun vollstaendig implementiert und produktiv:

Naechste Schritte

• Prometheus Metriken fuer Update-Erfolgsrate
• Grafana Dashboard fuer Container-Versionen
• n8n Workflow fuer Update-Reports
• Discord Webhook als zusaetzlicher Benachrichtigungskanal