Eigene Anpassungen am Stack (docker-compose.override.yml)¶

Du willst die Vesana-Container an deine Umgebung anpassen, zum Beispiel:

den Vesana-Webserver in das Docker-Netz deines Reverse-Proxys hängen (Nginx Proxy Manager, Traefik, Caddy)
ein Overlay-Netz über mehrere Hosts nutzen (Docker Swarm)
Labels setzen (Traefik-Routing, Watchtower-Ausnahme, Backup-Werkzeuge)
Ressourcen-Grenzen (mem_limit, cpus) oder eigene Bind-Mounts ergänzen

Dafür gibt es genau einen Ort: die Datei docker-compose.override.yml im Installationsverzeichnis (Standard /opt/vesana), direkt neben docker-compose.prod.yml.

Warum nicht in docker-compose.prod.yml oder der .env?¶

Datei	Gehört	Bei einem Update
`docker-compose.prod.yml`	Vesana	wird ersetzt (Online-Update lädt sie vom Lizenzportal, Offline-Update aus dem Paket; die alte Fassung landet als Sicherung im Updater-Volume)
`.env`	dir	bleibt erhalten — der Updater ändert nur einzelne eigene Zeilen (z. B. `VESANA_VERSION`, Compose-Profile, Größenprofil, Agent-Gateway-Port). Die `.env` kann aber nur Werte setzen, keine Netze, Labels oder Mounts
`docker-compose.override.yml`	dir	bleibt unverändert. Vesana liest sie bei jedem Update und jedem Neustart mit, schreibt, sichert oder löscht sie aber nie

Änderungen direkt in docker-compose.prod.yml sind also nach dem nächsten Update weg.

So legst du sie an¶

Datei anlegen, sie enthält nur deine Ergänzungen:

# /opt/vesana/docker-compose.override.yml
services:
  nginx:
    labels:
      com.example.team: "monitoring"

Prüfen, ob Compose beide Dateien zusammen versteht:

cd /opt/vesana
docker compose -f docker-compose.prod.yml -f docker-compose.override.yml config --quiet && echo ok

Anwenden:

docker compose -f docker-compose.prod.yml -f docker-compose.override.yml up -d

Ab jetzt nimmt Vesana die Datei bei allem mit, was den Stack neu anlegt: GUI-Update, automatisches Update, Offline-Update, Agent-Gateway- und Ollama-Schalter, Split-Container-Assistent, Größenprofil.

Befehle von Hand ohne zweimal -f

Trägst du in die .env die Zeile COMPOSE_FILE=docker-compose.prod.yml:docker-compose.override.yml ein, reicht im Installationsverzeichnis ein schlichtes docker compose up -d. Der Updater braucht die Zeile nicht, er findet die Datei selbst.

Beispiele¶

Webserver ins Netz eines Reverse-Proxys hängen¶

Dein Reverse-Proxy (z. B. Nginx Proxy Manager) läuft in einem eigenen Docker-Netz proxy. So erreicht er Vesana unter dem Namen nginx, ohne dass Port 443 auf dem Host offen sein muss:

services:
  nginx:
    networks:
      - default
      - proxy

networks:
  proxy:
    external: true

Wichtig: default muss in der Liste bleiben, sonst erreicht der Webserver die Vesana-API nicht mehr.

Overlay-Netz über mehrere Hosts (Docker Swarm)¶

Ein Compose-Stack kann sich an ein attachable Overlay-Netz hängen, das du im Swarm angelegt hast:

# einmalig auf einem Swarm-Manager
docker network create --driver overlay --attachable --opt encrypted proxy-overlay

services:
  nginx:
    networks:
      - default
      - proxy-overlay

networks:
  proxy-overlay:
    external: true

Bedenke dabei:

Vesana läuft weiterhin als normaler Compose-Stack. Als Swarm-Stack (docker stack deploy) läuft es nicht, und der Updater kann das auch nicht aktualisieren.
Ist das Overlay-Netz nicht verfügbar (Swarm gestört), startet der nginx-Container nicht, auch nicht nach einem Update. Vesana hängt dann an deiner Swarm-Infrastruktur.
Ohne --opt encrypted läuft der Verkehr zwischen den Hosts unverschlüsselt (VXLAN).

Labels (Traefik, Backup-Werkzeuge, Watchtower)¶

services:
  nginx:
    labels:
      traefik.enable: "true"
      com.centurylinklabs.watchtower.enable: "false"

Der Vesana-Webserver spricht im Container HTTPS auf Port 443 mit dem Zertifikat des Stacks. Ein Proxy davor muss also per HTTPS weiterleiten und diesem Zertifikat vertrauen oder die Prüfung für dieses eine Ziel abschalten.

Ressourcen-Grenzen¶

services:
  worker:
    mem_limit: 2g
  ollama:
    cpus: 4

Für Arbeitsspeicher und Worker-Zahl gibt es auch das eingebaute Größenprofil (siehe Ressourcen). Nimm die Override-Datei nur für das, was das Profil nicht abdeckt.

Was Vesana zusichert und was nicht¶

Zugesichert:

Die Datei wird bei jedem Update und jedem Neustart durch Vesana mitgeladen.
Vesana verändert sie nie.
Vorabprüfung vor jedem Update: Nach dem Laden der neuen docker-compose.prod.yml prüft der Updater beide Dateien zusammen (docker compose config). Passen sie nicht mehr zusammen, bricht das Update ab, bevor etwas gezogen oder gestoppt wird. Die alte Compose-Datei wird wiederhergestellt, und Vesana läuft auf der bisherigen Version weiter. Die Meldung auf der Update-Seite nennt die Datei und den Fehler von Compose.

Nicht zugesichert:

Dienstnamen und interne Details sind keine feste Schnittstelle. Benennt ein Release einen Dienst um oder ändert seine Netze, musst du deine Datei anpassen. Die Vorabprüfung sorgt dafür, dass du das merkst, bevor etwas kaputtgeht.
Ein Fehler, der durch deine Ergänzungen entsteht, ist nicht durch den Vesana-Support abgedeckt. Das Support-Bundle zeigt, dass eine Override-Datei aktiv ist und welche Dienste sie anfasst (nur Namen, keine Werte).

Sicherheit: was nie in ein fremdes Netz gehört¶

Hänge nur den Webserver (nginx) in fremde Netze. Niemals api, api-admin, postgres, redis, updater oder die Worker.

Vesana vertraut seinen eigenen Stack-Netzen als Proxy. Hängt die API in einem fremden Netz, gilt dieses Netz automatisch als vertrauenswürdig. Jeder Container darin könnte dann seine Absenderadresse fälschen und so die Admin-IP-Allowlist umgehen.
postgres und redis sollen ausschließlich im Stack-Netz erreichbar sein.
Der updater hält den Docker-Socket, er darf nie aus einem anderen Netz erreichbar sein.
Veröffentliche keine zusätzlichen Ports (ports:) für diese Dienste.

Hinter einem Reverse-Proxy: drei Punkte¶

Egal ob dein Proxy Vesana über ein gemeinsames Docker-Netz oder über https://<server>:443 erreicht:

Echte Client-Adressen: Trage die Adresse bzw. das Netz deines Proxys unter Admin → Anmeldung & Sicherheit → Admin-Zugriff → „Erweitert: Reverse-Proxies (X-Forwarded-For)" als vertrauenswürdigen Proxy ein. Sonst sehen Anmelde-Sperren, Sitzungsliste und Audit-Log alle Nutzer mit der Adresse des Proxys.
Agent-Gateway (Port 8443) nicht entschlüsseln: Agents und Collectors prüfen dort das Zertifikat des Vesana-Stacks. Leite den Port als reinen TCP-Stream durch (Nginx Proxy Manager: „Streams“) oder lass ihn direkt erreichbar. Siehe Distribution & Erreichbarkeit.
Adresse: Die Adresse, unter der Nutzer Vesana öffnen, ist die des Proxys, ohne Port.

Rückgängig machen¶

Datei umbenennen oder löschen und den Stack neu anlegen:

cd /opt/vesana
mv docker-compose.override.yml docker-compose.override.yml.aus
docker compose -f docker-compose.prod.yml up -d