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

/opt/vesana/
├── docker-compose.prod.yml      # Compose-Stack-Definition
├── .env                         # Secrets + Konfiguration
├── secrets/                     # Datei-Secrets (chmod 600)
│   ├── pg_password
│   ├── redis_password
│   ├── secret_key
│   └── field_encryption_key
├── ssl/                         # TLS-Zertifikate (optional, sonst self-signed)
│   ├── cert.pem
│   └── key.pem
├── backups/                     # Sicherungen wenn Profil "backup" aktiv
└── uploads/                     # Wiki-Anhänge etc.

Optionale Profile

Compose-Profile schalten optionale Services an:

Profil Services Wann
Default (kein Profil) postgres, redis, api, receiver, worker, frontend, init Immer
ai ollama AI-Features mit lokalem Ollama
backup backup-sidecar Tägliches Backup
pgbouncer pgbouncer Connection-Pool bei vielen API-Replicas

Aktivieren:

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

Die Profile sind kumulativ — einmal aktiviert, bleiben die Services auch bei up -d ohne Profil-Flag. Zum Deaktivieren explizit down <service>.

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 JWT-Signaturschlüssel, generiert
FIELD_ENCRYPTION_KEY AES-256-GCM-Key für Feldverschlüsselung, generiert

Optional / Tuning

Variable Default Bedeutung
WORKER_REPLICAS 1 Anzahl Consumer-Worker
WORKER_CONCURRENCY 4 Parallelität pro Worker
WORKER_BATCH_SIZE 100 Batch-Größe pro Durchlauf
PG_SHARED_BUFFERS 256MB ~25 % vom RAM
PG_WORK_MEM 16MB Sort/Hash-Buffer
PG_EFFECTIVE_CACHE 512MB ~50 % vom RAM
PG_MAX_CONNECTIONS 200 Connection-Limit
REDIS_MAXMEMORY 512mb Redis-Speicherlimit (noeviction-Policy)
HTTP_PORT / HTTPS_PORT 80 / 443 Wenn andere Dienste die Ports belegen
AI_ENABLED false AI-Features einschalten
LICENSE_KEY leer Lizenzschlüssel
VESANA_TESTER_MODE false Tester-Mode (alle Features frei)

Vollständige Liste in .env.example. Nach Änderungen docker compose up -d zum Übernehmen.

SSL / TLS

Standard: Let's Encrypt vom Setup-Wizard

Wenn BASE_URL eine Domain enthält und Port 80 von außen erreichbar ist, beantragt der Wizard automatisch ein Let's-Encrypt-Cert. Renewal läuft im Hintergrund.

Eigenes Zertifikat

sudo cp dein-cert.pem /opt/vesana/ssl/cert.pem
sudo cp dein-key.pem  /opt/vesana/ssl/key.pem
sudo chmod 600 /opt/vesana/ssl/key.pem

docker compose -f /opt/vesana/docker-compose.prod.yml exec nginx nginx -s reload

Hinter eigenem Reverse-Proxy

Wenn der Server bereits hinter einem nginx / Traefik / HAProxy steht, terminiere TLS dort und proxiere intern auf http://vesana-frontend:80. Details: TLS / Reverse-Proxy.

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-Step. Die Instanz registriert sich beim Lizenzportal als „Tester-Instanz" und Lukas/das Vendor-Team kann ihr server-seitig Updates abdrehen.

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

  • shared/license.py::is_tester_mode() returnt True
  • load_license_from_env_or_db() liefert eine synthetische Full-Features-LicenseInfo
  • Der API-Server phone-homed alle 60 Minuten an license.vesana.org/api/v1/tester/register mit {instance_id, hostname, version}
  • Im Lizenzportal erscheint die Instanz unter „Tester-Instanzen"
  • Updates können dort pro Instanz auf blocked gestellt 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

Anschluss