Zum Inhalt

Installation

Ein Befehl, als root ausgeführt — mehr braucht es nicht. Empfohlen ist ein frisches Debian 13 in einer eigenen VM (siehe Voraussetzungen), es geht aber genauso auf Ubuntu oder neben anderen Diensten:

curl -fsSL https://vesana.org/install | bash

Falls curl fehlt (minimales Debian), geht auch wget:

wget -qO- https://vesana.org/install | bash

Als root, ohne sudo

Der Installer braucht Root-Rechte (Docker, /opt, systemd). Auf Debian ist sudo oft gar nicht installiert — deshalb vorher als root anmelden: su - (Debian) bzw. sudo -i (Ubuntu), dann den One-Liner ausführen.

Was der Installer macht

[1/6] Checking system            – Architektur, RAM, Ports 80/443
[2/6] Installing prerequisites   – openssl/curl, Docker (falls nötig)
[3/6] Downloading Vesana         – Compose-Datei + Konfigurations-Vorlage
[4/6] Configuration              – Server-Adresse, Lizenzschlüssel (optional)
[5/6] Generating secrets         – Passwörter, Verschlüsselungs-Schlüssel
[6/6] Starting Vesana            – Images laden, Stack starten, auf Health warten,
                                   Active-Checker-Einrichtung vormerken

Lange Schritte (Docker-Installation, Image-Download) laufen still im Hintergrund — die vollständige Ausgabe landet in /var/log/vesana-install.log.

Gefragt wird nur nach zwei Dingen:

  1. Adresse unter der Vesana im Browser erreichbar sein soll (Vorschlag: die erkannte Server-IP — Enter übernimmt sie)
  2. Lizenzschlüssel — Enter überspringt ihn (freie Community Edition)

Danach öffnet sich der Weg in den Browser: https://<deine-adresse>/setup startet den Setup-Wizard. Die Zertifikatswarnung beim ersten Aufruf ist normal (selbstsigniertes Zertifikat).

Der Installer druckt am Ende einen Setup-Link mit einem einmaligen Code (…/setup?setup_token=…) und den Code noch einmal darunter. Öffnest du /setup von Hand, fragt der Assistent nach diesem Code — du kannst den Code oder einfach den ganzen Link ins Feld kopieren. Er steht auch in der .env als VESANA_SETUP_TOKEN. So kann in den Minuten zwischen Installation und Abschluss niemand Fremdes die Instanz einrichten. Nach dem Abschluss ist der Code ohne Bedeutung.

Setup-Code wiederfinden

Ist die Ausgabe des Installers weg, steht der Code auf dem Server in der .env:

grep VESANA_SETUP_TOKEN /opt/vesana/.env

Dann https://<deine-adresse>/setup?setup_token=<code> öffnen, oder /setup aufrufen und den Code ins Feld eintragen. Er gilt, bis der Setup-Wizard abgeschlossen ist.

Port 80 oder 443 belegt

Läuft auf dem Server schon ein Webserver (Apache, nginx, ein Reverse-Proxy), meldet der Installer in Schritt 1 ports 80/443 are already in use und bietet an, Vesana auf anderen Ports zu betreiben — der andere Dienst läuft weiter:

? HTTPS port for Vesana [9443]:
? HTTP port (only redirects to HTTPS) [9080]:

Enter übernimmt den Vorschlag (immer ein gerade freier Port; ein freier Standard-Port bleibt der Vorschlag). Die Adresse im nächsten Schritt schlägt den Port gleich mit vor (https://<ip>:9443) — er gehört dazu, denn unter dieser Adresse melden sich später auch Agents und Collectors. Nur hinter einem Reverse-Proxy, der selbst an 443 lauscht, lässt man ihn weg. Läuft eine Firewall (z. B. ufw), den gewählten HTTPS-Port dort freigeben. Am Ende stehen wie gewohnt Setup-Link und Setup-Code.

Für eine Installation ohne Terminal gibt es dieselbe Wahl als Umgebungsvariablen VESANA_HTTPS_PORT und VESANA_HTTP_PORT (siehe Unbeaufsichtigte Installation).

Antwortest du auf die Port-Frage mit n, kannst du Vesana trotzdem installieren (ohne Start) und später selbst umstellen:

  1. Andere Ports eintragen in /opt/vesana/.env, zum Beispiel:

    HTTP_PORT=9080
HTTPS_PORT=9443
BASE_URL=https://192.168.1.50:9443

    Der Port gehört auch in BASE_URL — unter dieser Adresse melden sich später Agents und Collectors. Alternativ den anderen Dienst stoppen (z. B. systemctl disable --now apache2), dann bleibt alles bei 80/443.

  2. Den Installer noch einmal ausführen (derselbe One-Liner). Er erkennt die vorhandene .env, lässt die Konfiguration unangetastet, überspringt die Port-Prüfung, startet Vesana und gibt am Ende den Setup-Link mit Code und neuem Port aus.

Wer stattdessen docker compose -f /opt/vesana/docker-compose.prod.yml up -d von Hand startet, bekommt keinen Link angezeigt — dann den Code wie oben unter Setup-Code wiederfinden aus der .env holen.

Active-Checker & erster Netzwerk-Scan

Mit der Installation wird automatisch der Active-Checker (Aktiver Collector) eingerichtet: aktive Checks wie Ping/SNMP/HTTP direkt vom Vesana-Server. Er läuft als systemd-Dienst auf dem Server, außerhalb von Docker. Der Installer legt dafür einen systemd-Timer (vesana-ac-autoinstall.timer) an, der alle 3 Minuten nachsieht und den Dienst einrichtet, sobald der Setup-Wizard abgeschlossen ist — typisch 1–3 Minuten danach, auch über einen Neustart hinweg. Danach schaltet sich der Timer selbst ab.

Beim ersten Kontakt sucht er einmalig nach den erreichbaren Netzen und durchsucht bis zu drei kleine private IPv4-Netze (höchstens /22, z. B. 192.168.1.0/24) einmal nach Geräten — die Funde stehen unter Discovery. Öffentliche Netze (etwa das Netz eines Mietservers beim Hoster) durchsucht er nie von selbst. Kommt der Active-Checker binnen 14 Tagen nicht online, entfällt dieser Erst-Scan.

Status und etwaige Fehler: Admin → Agents & Collectors → Active-Checker (+ Diagnose-Log), Protokoll des Einrichtungs-Timers: journalctl -u vesana-ac-autoinstall.

FIELD_ENCRYPTION_KEY sichern

Schlüsselverlust = Datenverlust

Der Installer zeigt am Ende von Schritt 5 den FIELD_ENCRYPTION_KEY an. Er schützt verschlüsselte Felder (z. B. SNMP-Communities) und ist bewusst nicht Teil von Backups. Geht er verloren, sind diese Daten dauerhaft unwiederbringlich.

Sofort nach der Installation:

  1. Schlüssel aus der Ausgabe kopieren (auch in /opt/vesana/secrets/)
  2. In einem Passwort-Manager hinterlegen (Bitwarden, 1Password, KeePass)
  3. Zusätzlich offline oder in einem getrennten Backup ablegen

IPv6 (optional)

Vesana veröffentlicht seine Ports standardmäßig nur über IPv4. Soll es auch über IPv6 erreichbar sein, trage VESANA_IPV6=true in /opt/vesana/.env ein (bei der Installation: VESANA_IPV6=true als Umgebungsvariable) und führe das nächste Update aus. Das setzt Docker 27 oder neuer mit IPv6-NAT voraus; kann Docker das nicht (zu alt, rootless, ip6tables abgeschaltet), bleibt Vesana bei IPv4 und nennt den Grund im Updater-Log bzw. im Installer. Ports mit fester Adresse (HTTP_PORT=127.0.0.1:8285) bleiben unverändert.

Unbeaufsichtigte Installation (Automation)

Jede Frage hat eine Umgebungsvariable — damit läuft der Installer ohne Terminal (Ansible, cloud-init, CI):

VESANA_BASE_URL=https://monitoring.example.com \
  bash <(curl -fsSL https://vesana.org/install)
Variable Bedeutung
VESANA_BASE_URL Server-Adresse (Pflicht für unbeaufsichtigt)
VESANA_LICENSE_KEY Lizenzschlüssel (leer = Community)
VESANA_DIR Installationsverzeichnis (Default /opt/vesana)
VESANA_REGISTRY_USER / VESANA_REGISTRY_TOKEN Private Registry (Enterprise)
VESANA_HTTPS_PORT / VESANA_HTTP_PORT andere Ports als 443/80 (z. B. wenn ein Webserver sie belegt)
VESANA_IPV6 true = Ports zusätzlich über IPv6 veröffentlichen (Standard: nur IPv4; braucht Docker 27+ mit IPv6-NAT)
VESANA_VERSION bestimmte Version installieren (Image-Tag, z. B. v1.903.0); ohne = aktuelle freigegebene Version
VESANA_PG_SIZING default = Postgres-Speicherwerte der Vorlage behalten, statt sie aus dem RAM abzuleiten (siehe Self-Hosting)
VESANA_PULSE off = Instanz meldet keinen Instanz-Puls (Test-/Wegwerf-Installationen)
VESANA_NO_START beliebiger Wert (z. B. 1) = installieren, aber nicht starten
VESANA_NONINTERACTIVE beliebiger Wert = keine Rückfragen, auch wenn ein Terminal da ist

Re-Run

Der Installer ist wiederholbar: existiert /opt/vesana/.env bereits, bleibt die Konfiguration unangetastet (keine Secrets-Rotation; zu offene Dateirechte der .env werden auf „nur root" korrigiert) — er stellt sicher, dass der Stack läuft. Dabei lädt er die aktuelle Compose-Datei und die Images neu; ohne festgelegte VESANA_VERSION in der .env landet die Instanz damit auf der aktuellen freigegebenen Version — ohne das Pre-Update-Backup des GUI-Updaters. Auf einer produktiven Instanz deshalb nicht als Update-Ersatz verwenden. Für eine komplette Neuinstallation: docker compose -f /opt/vesana/docker-compose.prod.yml down -v (löscht alle Daten!), dann rm /opt/vesana/.env und den One-Liner erneut ausführen.

Anschluss