Zum Inhalt

Self-Hosting-Übersicht

Diese Seite ist die Referenz für Operations-Aufgaben rund um Vesana. Wenn du Vesana für andere hostest oder bei einem Kunden eine Instanz pflegst: hier sind die Hebel.

Verzeichnisstruktur

Auf dem Host selbst liegen nur zwei Dinge in /opt/vesana/:

/opt/vesana/
├── docker-compose.prod.yml      # Compose-Stack-Definition
└── .env                         # Secrets + Konfiguration (Klartext-Umgebungsvariablen)

Alles andere — SSL-Zertifikate, Backups, Agent-/Collector-Binaries, Uploads, Icon-Assets, Avatare — liegt in benannten Docker-Volumes, nicht als Verzeichnis unter /opt/vesana. Das hat den Vorteil, dass ein docker compose down (ohne -v) niemals versehentlich Daten aus einem Host-Verzeichnis mitreißt.

Willst du in ein Volume hineinschauen oder etwas herauskopieren, geht das über einen Wegwerf-Container:

# Beispiel: Inhalt eines Volumes auflisten
docker run --rm -v vesana_backup-data:/data alpine ls -la /data

# Beispiel: Datei aus einem Volume herauskopieren
docker run --rm -v vesana_backup-data:/src -v $(pwd):/dst alpine \
  sh -c 'cp /src/irgendeine-datei /dst/'

(Volume-Namen tragen üblicherweise den Compose-Projekt-Präfix, z. B. vesana_backup-data — mit docker volume ls prüfen, falls der Präfix bei dir abweicht.)

Optionale Compose-Profile

Zwei optionale Profile schalten zusätzliche Services an:

Profil Service Wann
Default (kein Profil) postgres, redis, api, receiver, worker, worker-scheduler, nginx, init Immer
ai ollama AI-Features mit lokalem Ollama
agent-gateway agent-gateway Separater Port nur für Agent-/Collector-Endpunkte (Weboberfläche kann dann per Firewall abgeschottet werden) — siehe Distribution & Erreichbarkeit

Backups sind kein Profil mehr — das eingebaute DR-Backup-System (siehe Backup & Disaster-Recovery) läuft immer mit, ohne separaten Sidecar.

Aktivieren:

docker compose -f docker-compose.prod.yml --profile ai up -d

Oder dauerhaft über die .env:

COMPOSE_PROFILES=ai,agent-gateway

Wichtige Umgebungsvariablen

Die .env wird vom Setup-Script generiert. Wichtige Variablen:

Pflicht

Variable Bedeutung
BASE_URL Öffentliche URL inkl. https://
POSTGRES_PASSWORD Generiert
REDIS_PASSWORD Generiert
SECRET_KEY Signaturschlüssel für Login-Tokens, generiert
FIELD_ENCRYPTION_KEY AES-256-GCM-Key für Feldverschlüsselung, generiert

Optional / Tuning

Variable Default Bedeutung
WORKER_REPLICAS 1 Anzahl Consumer-Worker-Container
WORKER_CONCURRENCY 4 Parallelität pro Worker
WORKER_BATCH_SIZE 100 Batch-Größe pro DB-Insert-Durchlauf
DB_POOL_SIZE 10 Größe des DB-Connection-Pools
DB_MAX_OVERFLOW 20 Zusätzliche Connections über den Pool hinaus, bei Bedarf
PG_SHARED_BUFFERS 256MB Postgres-Puffer, ~25 % vom RAM als Faustregel
PG_WORK_MEM 16MB Sort-/Hash-Buffer pro Operation
PG_EFFECTIVE_CACHE 512MB Postgres-Planner-Annahme, ~50 % vom RAM
PG_MAX_CONNECTIONS 200 Connection-Limit
PG_MAINTENANCE_WORK_MEM 256MB Speicher-Deckel für Vacuum/Index-Wartung — ohne diesen Wert leitet die automatische Postgres-Tuning-Logik den Wert aus dem gesamten Host-RAM ab, was auf kleinen Maschinen zu OOM führen kann
REDIS_MAXMEMORY 512mb Redis-Speicherlimit (noeviction-Policy — Redis lehnt neue Daten ab statt alte zu verwerfen)
CHECK_RESULTS_RETENTION_DAYS 90 Startwert für die Messwerte-Retention (später über Ressourcen → Speicher änderbar)
LOG_RETENTION_DAYS 30 Startwert für die Log-Retention
HTTP_PORT / HTTPS_PORT 80 / 443 Wenn andere Dienste die Ports belegen
AGENT_GATEWAY_PORT 8443 Nur relevant mit aktivem agent-gateway-Profil
AI_ENABLED false AI-Features einschalten
LICENSE_KEY leer Lizenzschlüssel
VESANA_TESTER_MODE false Tester-Mode (alle Features frei)

Die vier Sizing-Profile (Klein/Mittel/Groß/XL) unter Ressourcen → Leistung setzen WORKER_REPLICAS, WORKER_CONCURRENCY, PG_SHARED_BUFFERS, PG_EFFECTIVE_CACHE, PG_WORK_MEM, PG_MAINTENANCE_WORK_MEM, PG_MAX_CONNECTIONS, DB_POOL_SIZE/DB_MAX_OVERFLOW und REDIS_MAXMEMORY in einem Rutsch — für die meisten Setups einfacher als einzelne Variablen von Hand zu justieren.

Vollständige Liste der verfügbaren Variablen in der mitgelieferten .env.example. Nach Änderungen: docker compose up -d zum Übernehmen.

SSL / TLS

Standard: automatisches selbstsigniertes Zertifikat

Beim ersten Start generiert Vesana automatisch ein selbstsigniertes Zertifikat — dadurch läuft der Setup-Wizard immer über HTTPS, auch ganz ohne eigene Domain oder eigenes Zertifikat. Dein Browser zeigt dafür eine Zertifikatswarnung, bis du ein echtes Zertifikat einspielst.

Es gibt keine eingebaute automatische Let's-Encrypt-Ausstellung — die Ausstellung und Erneuerung eines öffentlichen Zertifikats musst du selbst organisieren (z. B. mit certbot auf dem Host oder über einen vorgeschalteten Reverse-Proxy, siehe unten).

Eigenes Zertifikat einspielen

Zertifikat und Key liegen im Container unter /etc/nginx/ssl/fullchain.pem und /etc/nginx/ssl/privkey.pem — das ist ein benanntes Docker-Volume, kein Host-Verzeichnis. Eigenes Zertifikat reinkopieren:

docker run --rm \
  -v vesana_ssl:/etc/nginx/ssl \
  -v /pfad/zu/deinem/cert:/src:ro \
  alpine sh -c 'cp /src/fullchain.pem /src/privkey.pem /etc/nginx/ssl/'

docker compose -f /opt/vesana/docker-compose.prod.yml restart nginx

Solange gültige Dateien unter diesen beiden Namen im Volume liegen, überschreibt Vesana sie beim Neustart nicht mit einem neuen selbstsignierten Zertifikat — Erneuerung (z. B. alle 90 Tage bei Let's Encrypt) musst du selbst per Cron-Job wiederholen (gleicher Befehl wie oben, danach nginx -s reload statt vollem Restart).

Hinter eigenem Reverse-Proxy

Wenn der Server bereits hinter einem eigenen nginx / Traefik / HAProxy steht, terminiere TLS dort und proxiere intern auf den Vesana-Webserver-Container. Details zu Reverse-Proxy-Besonderheiten (SSE-Buffering, WebSocket-Upgrade): Distribution & Erreichbarkeit.

Tester-Mode

Was ist Tester-Mode

Mit VESANA_TESTER_MODE=true in der .env wird die Lizenzprüfung umgangen — alle Features sind freigeschaltet, der Setup-Wizard überspringt den Lizenz-Schritt. Die Instanz registriert sich beim Lizenzportal als „Tester-Instanz" und kann dort serverseitig von Updates ausgeschlossen werden.

Aktivieren

echo "VESANA_TESTER_MODE=true" | sudo tee -a /opt/vesana/.env
docker compose -f /opt/vesana/docker-compose.prod.yml up -d

Was passiert

  • Die Lizenzprüfung liefert intern immer eine vollwertige Lizenz-Info zurück
  • Der API-Server meldet sich stündlich beim Lizenzportal als Tester-Instanz (Instanz-ID, Hostname, Version)
  • Im Lizenzportal erscheint die Instanz unter „Tester-Instanzen"
  • Updates können dort pro Instanz gesperrt werden — der Updater zeigt dann einen Banner

Wann Tester-Mode aus

Vor Übergabe an einen echten Kunden: VESANA_TESTER_MODE aus der .env entfernen, Lizenzschlüssel hinterlegen, Stack neu starten.

Updates & Backups

  • Updates — GUI-Updater, Online + Offline + Notfall-CLI, kein Auto-Rollback
  • Backup & Restore — eingebautes DR-System, mehrere Zeitpläne, Disaster-Drill

Anschluss