Troubleshooting und Diagnose¶

Eine strukturierte Anleitung zur Diagnose einer Stargate-Appliance über die Befehlszeile: was Sie prüfen sollten, wo sich die Logs befinden und welche Wiederherstellungsmassnahmen sicher sind.

Wo sich die Skripte befinden

Die Hilfsskripte liegen im Bereitstellungsverzeichnis unter scripts/. Die folgenden Befehle verwenden den vollständigen Pfad für VM-Images: /usr/share/stargate-deployment/docker-compose/scripts/. Wenn Sie an einem anderen Ort installiert haben, ersetzen Sie ihn durch Ihr eigenes Installationsverzeichnis (den Ordner, der docker-compose.yml und scripts/ enthält).

docker compose ...-Befehle müssen aus dem Bereitstellungsverzeichnis ausgeführt werden:

cd /usr/share/stargate-deployment/docker-compose   # adjust to your install path

Wo sich die beschreibbaren Daten befinden

Der obige docker-compose/-Verzeichnisbaum (Skripte, docker-compose.yml, Konfigurationsvorlagen) ist zur Laufzeit schreibgeschützt. Alle beschreibbaren Daten liegen stattdessen unter /var/data: .env, customer-config.sh, secrets/, die generierte TLS-, Keycloak- und APISIX-Konfiguration, Backups sowie die eigenen Daten jedes Dienstes (STARGATE_DATA_DIR überschreibt dieses Stammverzeichnis für Tests). Im Einzelnen: Konfiguration und Secrets liegen unter /var/data/vereign/ und Backups unter /var/data/backups/. Die vollständige Übersicht finden Sie unter Docker erweiterte Konfiguration. Verwenden Sie bevorzugt die Wrapper-Skripte (./scripts/start.sh, ./scripts/stop.sh, ...) statt eines blossen docker compose up -d, das /var/data/vereign/.env nicht von selbst einliest.

1. Erster Schritt: der Health Check¶

Ein einziger Befehl gibt einen Überblick über die gesamte Appliance:

QuickVerbose

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v

Er meldet «bestanden» oder «fehlgeschlagen» für: Container (running/healthy), Liveness-Endpunkte (smimekeys, policy, irisagent, mxengine), den Vault-Siegelstatus, die PostgreSQL-Verbindung und -Datenbanken, SeaweedFS, den WireGuard-Tunnel und die Peer-Handshakes, den Stalwart-MTA (Ports 25 / 10026), die Prometheus-Metrik-Endpunkte sowie Festplatte und Arbeitsspeicher.

Tip

Führen Sie diesen Befehl zuerst aus. Eine einzelne FAIL-Zeile führt Sie in der Regel direkt zum passenden Abschnitt weiter unten.

2. Wo sich die Logs befinden¶

Ebene	Befehl	Was angezeigt wird
Systemstart / Erstinstallation / Autostart	`sudo journalctl -u stargate -n 200 --no-pager`	Der systemd-Dienst, der `start.sh` beim Systemstart ausführt, sowie die Installation beim ersten Start
Updates (VM-Appliance)	`hingateway-status`, `docker logs stargate-ops-agent --tail 100` und `journalctl -u greenboot-healthcheck`	Gestartete, bereitgestellte und Rollback-Betriebssystemversion; Backup, Download und Fehler eines Updates (nur bis zum nächsten Neustart); Ergebnis des Boot-Health-Checks
`update.sh`-Läufe	`cat /var/data/vereign/update.log`	Ausgabe aller `update.sh`-Läufe, der neueste steht am Ende: Updates reiner Compose-Installationen, Dashboard-Updates auf älteren VMs vor bootc und Läufe nach Änderungen an `customer-config.sh`
Ein einzelner Dienst	`docker logs stargate-<service> --tail 100`	z. B. `stargate-dashboard`, `stargate-mxengine`, `stargate-keycloak`
Einen Dienst live verfolgen	`docker logs -f stargate-mxengine`	Echtzeit
Alle Container live	`docker ps -a --format '{{.Names}}' \\| xargs -I{} sh -c 'docker logs --timestamps -f {} 2>&1 \\| sed "s/^/[{}] /"'`	Zusammengeführt, mit dem Containernamen als Präfix
Web-Log-Viewer	Dozzle unter `https://<SERVER_IP>:8190` (Keycloak-Anmeldung)	Alle Container-Logs in einer Weboberfläche durchsuchen

Um Logs an den HIN-Support zu übermitteln, verwenden Sie das Upload-Skript: Es sammelt die letzten N Log-Zeilen aller Dienste (zusammen mit Host- und Versionsinformationen), lädt sie hoch und gibt einen Link aus, den Sie weitergeben können. Siehe Logs an den Support senden:

/usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh --tail 5000     # last 5000 lines from each service
# other options:  --since 1h   |   --until 5m   |   --all   (no argument = --tail 500)

Der Upload ist auf 20 MB begrenzt. Verwenden Sie auf einer stark ausgelasteten Appliance daher besser --tail/--since statt --all.

3. Container laufen nicht oder starten ständig neu¶

docker compose ps -a --format 'table {{.Service}}\t{{.Status}}'

Prüfen Sie die Spalte Status:

Status	Bedeutung	Massnahme
`Up ... (healthy)`	Läuft einwandfrei	-
`Up ...` (ohne Health-Status)	Läuft; kein Health Check definiert	Prüfen Sie die `docker logs`, wenn Sie ein Problem vermuten
`Restarting`	Absturzschleife	`docker logs stargate-<svc>`: Beheben Sie die eigentliche Fehlerursache (Konfiguration, Secret, Abhängigkeit)
`Exited (0)`	Einmalige Initialisierung erfolgreich abgeschlossen (z. B. `*-init`, `vault-data-fixer`)	Normal
`Exited (1+)`	Fehlgeschlagen	`docker logs stargate-<svc>`: Die letzten Zeilen zeigen den Grund
`Created`	Nie gestartet, da eine Abhängigkeit nicht hochgefahren ist	Prüfen Sie, wovon der Dienst abhängt (`depends_on`, in der Regel Postgres/Vault), und beheben Sie zuerst dieses Problem

Einen einzelnen Dienst neu starten (sicher, ohne Datenverlust):

docker compose up -d <service>          # recreate one service
docker compose restart <service>        # just restart it

Startreihenfolge

Dienste warten auf ihre Abhängigkeiten (depends_on + Health Checks). Bei einem vollständigen Neustart sind kurze Meldungen wie connection refused / database system is starting up, während Postgres und Vault hochfahren, normal und verschwinden innerhalb einer Minute.

4. Diagnose anhand der Symptome¶

Dashboard oder Keycloak lädt nicht / Anmeldung nicht möglich¶

Beide laufen hinter Caddy: das Dashboard auf :443, Keycloak auf :8180.
Prüfen Sie die gesamte Kette: docker logs stargate-caddy, stargate-dashboard, stargate-keycloak, stargate-apisix.
Keycloak muss healthy sein, bevor das Dashboard funktioniert: docker compose ps keycloak.
Eine TLS-Warnung im Browser ist zu erwarten (selbstsigniertes Zertifikat): Akzeptieren Sie sie und fahren Sie fort.
Fehlgeschlagene Weiterleitungen bei der Anmeldung bedeuten in der Regel, dass die öffentliche URL nicht mit der Adresse übereinstimmt, über die Sie die Appliance erreichen. Prüfen Sie, ob KEYCLOAK_PUBLIC_URL / DASHBOARD_PUBLIC_URL in .env auf die IP-Adresse bzw. den Host verweisen, den Sie tatsächlich verwenden.

WireGuard-Tunnel ausgefallen / Zertifikatsausstellung schlägt fehl¶

Dies ist das häufigste Problem: Zertifikate lassen sich nicht ausstellen, wenn der Tunnel ausgefallen ist. Beheben Sie deshalb immer zuerst das Tunnelproblem.

/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v      # shows WireGuard peer + handshake status
docker logs stargate-irisagent | grep -iE "handshake|peer|cert|wireguard"

Stellen Sie sicher, dass die Firewall 19818 (UDP und TCP) eingehend und ausgehend zulässt.
Prüfen Sie, ob der Peer auf HIN-Seite registriert ist (Schritt durch den Support). Sie liefern dafür den öffentlichen WG-Schlüssel, DEPLOYMENT_NAME, SERVER_STATIC_IP und WG_INTERFACE_PORT.
Sobald der Tunnel einen aktuellen Handshake anzeigt, starten Sie die Zertifikatsausstellung erneut über das Dashboard.

Vault versiegelt oder Initialisierung fehlgeschlagen¶

docker compose exec vault vault status        # look for "Sealed: false"
docker logs stargate-vault-init

Vault muss entsiegelt sein, damit smimekeys, mxengine und policy funktionieren. Die Schlüssel liegen in /var/data/vereign/secrets/vault-keys.json.
Wenn vault-init mit einem Exit-Code ungleich null beendet wurde, fehlt die Schlüsseldatei möglicherweise oder ist beschädigt. Prüfen Sie die Logs dieses Containers; ein erneuter Aufruf von /usr/share/stargate-deployment/docker-compose/scripts/init-vault.sh versucht die Entsiegelung erneut.

/var/data/vereign/secrets/vault-keys.json nicht löschen

Geht diese Datei verloren, verlieren Sie den Zugriff auf alle gespeicherten Secrets. Bewahren Sie ein Backup auf.

PostgreSQL / Datenbankverbindung¶

docker compose exec postgres pg_isready -U postgres
docker logs stargate-postgres --tail 50

Eine vorübergehende Meldung the database system is starting up (57P03) unmittelbar nach einem Neustart ist normal: Die Dienste verbinden sich automatisch neu.
Anhaltende Authentifizierungsfehler bedeuten in der Regel, dass POSTGRES_PASSWORD in .env nicht mehr mit dem Datenvolume übereinstimmt. Beachten Sie die Hinweise zu Updates und Secrets und bearbeiten Sie diesen Wert nicht von Hand.

E-Mails werden nicht zugestellt¶

Eingehende E-Mails kommen auf :25 (Stalwart) an. Viele Cloud-Anbieter sperren Port 25 standardmässig:
```
nc -zv <this-server-ip> 25          # from an external host
docker logs stargate-stalwart --tail 100
```
Wenn 25 gesperrt ist, beantragen Sie bei Ihrem Anbieter eine Freigabe. - Ausgehende E-Mails und Sealing laufen über Stalwart → mxengine (:8084 HTTP, SMTP :1587): docker logs stargate-mxengine. - Mail-Schleifen erkennen Sie daran, dass dieselbe Nachricht immer wieder zirkuliert. Prüfen Sie, ob der MX-Eintrag Ihrer Domain nicht auf die IP-Adresse dieser Appliance selbst zurückverweist. - Das vorgesehene Routing ist unter Mail-Relay-Einrichtung und DNS-Einrichtung beschrieben.

Ein Update ist fehlgeschlagen¶

Auf der VM-Appliance führt der Ops-Agent ein Update aus dem Dashboard in drei Phasen aus: ein Backup (backup.sh), der Download des Ziel-Betriebssystem-Images (bootc switch) und der Neustart in dieses Image. Beginnen Sie mit:

docker logs stargate-ops-agent --tail 100     # the update orchestrator: backup, download, errors
hingateway-status                             # booted, staged and rollback OS versions

Der Ops-Agent-Container wird bei jedem Start neu erstellt; sein Log deckt ein Update daher nur bis zum Neustart der VM ab. Verwenden Sie nach einem Neustart stattdessen hingateway-status und journalctl -u greenboot-healthcheck.

Fehler beim Backup. Schlägt das Backup vor dem Update fehl, bricht der Ops-Agent das Update ab; es wurde also nichts verändert. Prüfen Sie die Fehlermeldung im Ops-Agent-Log und den freien Speicherplatz auf dem Data Disk (df -h /var/data) und starten Sie das Update anschliessend erneut.
Fehler beim Download. Der Update-Status im Dashboard zeigt den Fehler als bootc switch: ... an; das Ops-Agent-Log enthält nur os select failed mit dem Exit-Status. Meist erreicht die VM die Image-Registry nicht (prüfen Sie den ausgehenden Internetzugang und DNS) oder die Betriebssystem-Festplatte ist voll (df -h /sysroot). Die laufende Version ist davon nicht betroffen; starten Sie das Update erneut, sobald die Ursache behoben ist.
Heruntergeladen, aber die Version hat sich nicht geändert. Die neue Version wird erst durch einen Neustart aktiv. Haben Sie Later gewählt, starten Sie die VM neu (sudo systemctl reboot) und prüfen Sie erneut hingateway-status. Wurde die VM neu gestartet und zeigt trotzdem die alte Version als gestartet an, hat sie automatisch ein Rollback durchgeführt - siehe nächster Punkt.
Automatisches Rollback nach einem fehlgeschlagenen Start. Nach dem Start einer neuen Version laufen Health-Checks - unter anderem, ob Docker läuft, der Data Disk eingebunden ist und der Stargate-Stack funktioniert, dazu die Standard-Checks des Betriebssystems. Schlägt ein erforderlicher Check fehl, wird der Start als RED markiert und die VM startet selbstständig wieder die vorherige Version. journalctl -u greenboot-healthcheck zeigt, welcher Check fehlgeschlagen ist. Beheben Sie die Ursache, bevor Sie das Update erneut versuchen; ein blosser Neustart wiederholt dasselbe Rollback. Hat die neue Version bereits ein Datenbankschema geändert oder war das fehlgeschlagene Update das erste Upgrade auf ein Image mit Data-Disk-Unterstützung (der Stack zeigt dann ein leeres /var/data, Ihre Daten sind aber unverändert), lesen Sie die Rollback-Hinweise, bevor Sie etwas anderes tun.
Die neue Version startet, ist aber nicht funktionsfähig. Prüfen Sie den Boot-Health-Check mit journalctl -u greenboot-healthcheck und den Stack mit /usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v. Um zur vorherigen Version zurückzukehren, verwenden Sie Roll back im Dashboard oder führen Sie hingateway-rollback && sudo systemctl reboot aus - lesen Sie vorher die Rollback-Hinweise.
Prüfen Sie nach einem erfolgreichen Update, ob die Versionen übernommen wurden: /usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh (oder die Image-Tags in docker compose ps).
Hängt ein einzelner Dienst nach einem Update, erstellen Sie nur diesen Dienst neu: cd /usr/share/stargate-deployment/docker-compose && sudo docker compose --env-file /var/data/vereign/.env up -d --no-deps --force-recreate <service>. sudo ist nötig, weil nur root .env lesen kann, und --no-deps verhindert, dass Compose auch die Abhängigkeiten des Dienstes neu erstellt, etwa Vault, das danach versiegelt wäre. Existiert /var/data/vereign/docker-compose.override.yml (oder .yaml), fügen Sie nach --env-file /var/data/vereign/.env die Optionen -f docker-compose.yml -f <Override-Datei> hinzu, damit der Override weiterhin angewendet wird. Dienste, die zu einem Profil gehören, benötigen dieses ebenfalls: --profile dozzle für dozzle und oauth2-proxy, --profile keri-idagent für idagent und --profile keri-watcher für watcher.

Bei einer reinen Compose-Installation (einem selbst verwalteten git clone) gibt es kein Update über den Ops-Agent: Sie führen update.sh selbst aus, und die Ausgabe wird an /var/data/vereign/update.log angehängt; der neueste Lauf steht am Ende. Die Update-Schritte finden Sie unter Reine Compose-Installation.

Warning

Versuchen Sie nicht, ein Update auf der VM-Appliance mit git oder update.sh --release zu reparieren. /usr/share/stargate-deployment ist Teil des schreibgeschützten Betriebssystem-Images, und es gibt keinen Repository-Checkout, der zurückgesetzt werden könnte; Versionen ändern sich nur durch den Wechsel des Betriebssystem-Images.

Ältere VMs (vor dem bootc-Image)¶

VMs, die aus einem Image vor der bootc-Appliance installiert wurden, haben unter /usr/share/stargate-deployment einen Git-Checkout statt eines schreibgeschützten Betriebssystem-Images. Die obigen Schritte für die VM-Appliance gelten für sie nicht. Langfristig sollten sie auf eine bootc-Appliance migriert werden, wie im englischsprachigen Leitfaden «Migrating a Compose Deployment to a bootc Appliance» beschrieben. Bis dahin gilt das Folgende nur für diese älteren VMs. Auf ihnen führt der Ops-Agent update.sh aus, dessen Ausgabe an /var/data/vereign/update.log angehängt wird (der neueste Lauf steht am Ende) - prüfen Sie diese Datei zuerst, wenn ein Update fehlschlägt.

Das Update startet, aber nichts passiert (Update von einer älteren Version). Bleibt das Ops-Agent-Log bei pulling deployment repo ... stehen und geht das Update nicht weiter, enthält das Repository auf der VM höchstwahrscheinlich lokale Änderungen an einer versionierten Datei (meist eine von Hand angepasste docker-compose.yml). Dadurch verweigert der git checkout des Ops-Agents die Ausführung, und das Update bleibt stehen. Setzen Sie das Repository zwangsweise auf den neuesten Stand zurück und führen Sie das Update anschliessend erneut aus. Git ist die einzige verbindliche Quelle; dabei gehen ausschliesslich lokale Änderungen an versionierten Dateien verloren. customer-config.sh, .env und secrets/ liegen unter /var/data/vereign/, also ausserhalb des Repository-Checkouts, und bleiben immer erhalten:

cd /usr/share/stargate-deployment
sudo git fetch origin
sudo git checkout -f main
sudo git reset --hard origin/main
cd docker-compose
sudo /usr/share/stargate-deployment/docker-compose/scripts/update.sh

update.sh erzeugt .env neu, lädt die Images herunter und erstellt die betroffenen Dienste neu. Hat das Release Konfigurationsdateien geändert, führen Sie anschliessend sudo /usr/share/stargate-deployment/docker-compose/scripts/start.sh aus, damit alle Container die neuen Dateien übernehmen. Starten Sie nach Abschluss das Update erneut über das Dashboard; es läuft nun durch.

Warning

Verwenden Sie hier nicht git pull. In einem Arbeitsverzeichnis mit lokalen Änderungen bricht der Befehl mit der Meldung «local changes would be overwritten» ab und zwingt Sie zu einem Umweg über git stash, Merge-Konflikte oder eine manuelle Wiederherstellung. Die obige Abfolge aus git checkout -f und git reset --hard vermeidet das vollständig und ist der sichere, wiederholbare Weg, das Repository auf den aktuellen Stand zu bringen.

VMs mit v0.5.1¶

Die folgenden Schritte aktualisieren eine VM von v0.5.1 auf v0.5.3. Unter v0.5.x liegen .env, customer-config.sh und secrets/ im Checkout unter /usr/share/stargate-deployment/docker-compose/, nicht unter /var/data/vereign/. Melden Sie sich mit dem Linux-Administratorkonto an der VM an.

Bearbeiten Sie /usr/share/stargate-deployment/docker-compose/.env und setzen Sie die Ops-Agent-Version auf v0.0.3.
Bearbeiten Sie /usr/share/stargate-deployment/docker-compose/customer-config.sh und setzen Sie auch dort die Ops-Agent-Version auf v0.0.3.
Laden Sie die Release-Tags herunter: cd /usr/share/stargate-deployment && sudo git fetch --tags origin
Checken Sie das Ziel-Release aus: sudo git checkout v0.5.3. Checken Sie nicht main aus: Dieser Branch enthält die aktuellen Skripte, die das neuere /var/data-Layout erwarten.
Aktualisieren Sie den Ops-Agent-Container: cd docker-compose && sudo docker compose up -d ops-agent
Melden Sie sich im Dashboard an.
Öffnen Sie Settings.
Geben Sie im Abschnitt Update am Seitenende die Zielversion (v0.5.3) ein und starten Sie den Update-Vorgang.

Migrieren Sie die VM danach auf eine bootc-Appliance, wie im englischsprachigen Leitfaden «Migrating a Compose Deployment to a bootc Appliance» beschrieben.

Dozzle (Log-Viewer) nicht erreichbar¶

Die URL lautet https://<SERVER_IP>:8190; erforderlich ist eine Keycloak-Anmeldung (derselbe Realm wie beim Dashboard) über oauth2-proxy.
Dozzle läuft nur, wenn DOZZLE_ENABLED="true" gesetzt ist. Prüfen: docker compose ps dozzle oauth2-proxy.
Stellen Sie sicher, dass die Firewall :8190 eingehend zulässt. Siehe Überwachung und Logs.

Onboarding: Die Eingabe des Aktivierungscodes führt zu einem Fehler¶

Wird der Aktivierungscode abgelehnt, prüfen Sie der Reihe nach:

Falscher Code: Der Code wurde nicht vollständig kopiert (abgeschnitten beim Kopieren, ein zusätzliches Leerzeichen oder ein fehlendes Zeichen). Kopieren Sie den vollständigen Code erneut und geben Sie ihn nochmals ein.
Code bereits verwendet: Der Code wurde bereits bei einem früheren Onboarding eingelöst. Fordern Sie einen neuen Code an.
WireGuard / Verbindung zu HIN: Der irisagent-Tunnel steht nicht, deshalb kann der Code nicht bei HIN validiert werden. Siehe oben WireGuard-Tunnel ausgefallen (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v, docker logs stargate-irisagent).
Keine Domain mit der Registrierung verknüpft: Mit der HIN-Registrierung des Kunden ist keine Domain verknüpft, es gibt also nichts zu aktivieren. Dies wird auf HIN-Seite behoben.

Onboarding: Aktivierungscode akzeptiert, aber es werden keine Domains angezeigt¶

Wahrscheinlichste Ursache: Der WireGuard-Tunnel ist nicht aufgebaut, meist wegen einer falschen öffentlichen IP-Adresse oder eines nicht geöffneten Firewall-Ports. Ohne Tunnel kann die Appliance die Domainliste nicht von HIN abrufen.

Prüfen Sie, ob SERVER_STATIC_IP in customer-config.sh mit der tatsächlichen öffentlichen IP-Adresse übereinstimmt.
Stellen Sie sicher, dass 19818 (UDP und TCP) eingehend und ausgehend offen ist.
Stellen Sie sicher, dass der Peer auf HIN-Seite für diese IP-Adresse registriert ist (Schritt durch den Support).
docker logs stargate-irisagent sollte einen aktuellen Handshake zeigen. Falls nicht, beheben Sie zuerst das Tunnelproblem (siehe oben WireGuard-Tunnel ausgefallen).

Server-IP-Adresse ändern (nur bei der Ersteinrichtung)¶

War die Server-IP-Adresse beim ersten Start falsch oder nicht gesetzt, setzen Sie das System sauber zurück und installieren Sie es neu. Sichern Sie zuerst die Konfiguration, denn purge.sh löscht auch customer-config.sh:

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh --config-only  # saves customer-config.sh
/usr/share/stargate-deployment/docker-compose/scripts/purge.sh                 # destroys ALL data - see warning below
/usr/share/stargate-deployment/docker-compose/scripts/restore.sh --config-only /var/data/backups/<timestamp>_config-only.tar.gz
nano /var/data/vereign/customer-config.sh    # set SERVER_STATIC_IP=<NEW IP>
reboot                                       # installs again with the new IP

backup.sh gibt den genauen Befehl für die Wiederherstellung aus, und das Archiv bleibt in /var/data/backups, das purge.sh nicht löscht. Der Neustart führt die Installation aus und lädt auch die lokal gebauten Images neu, die purge.sh entfernt. Bei einer reinen Docker-Installation führen Sie statt des Neustarts install.sh aus.

Das TLS-Zertifikat und mehrere Dienst-URLs werden beim ersten Start aus der IP-Adresse abgeleitet. Purge und Neuinstallation erzeugen sie daher für die neue Adresse neu. Die wiederhergestellte Datei behält die generierten Passwörter und den WireGuard-Schlüssel. Ist das Gateway bereits bei HIN registriert, muss die Registrierung mit der neuen IP-Adresse aktualisiert werden.

Nur vor dem Onboarding

purge.sh löscht alle Daten unwiderruflich: Datenbanken, Vault und die S/MIME-Schlüssel. Dies ist nur auf einer neuen, noch nicht onboardeten Appliance sicher. Führen Sie purge.sh niemals aus, um die IP-Adresse eines produktiven oder bereits onboardeten Gateways zu ändern: Das führt zu Datenverlust und zu E-Mails, die sich nicht mehr entschlüsseln lassen. Für eine IP-Änderung im Produktivbetrieb wenden Sie sich an den Support.

5. Speicher und Festplatte¶

df -h /                              # is the disk full?
docker system df                     # space used by images / containers / volumes
du -sh /var/lib/docker/volumes/*     # per-volume usage (Postgres, SeaweedFS, Loki, ...)

Container-Logs sind begrenzt (json-file, 100 MB × 5 pro Container) und sollten die Festplatte daher nicht füllen; Images und Volumes hingegen können das.
Speicherplatz sicher freigeben: docker image prune -af (entfernt nur nicht verwendete Images). Vermeiden Sie docker system prune --volumes, denn dieser Befehl löscht Daten-Volumes.
Als Objektspeicher dient SeaweedFS (stargate-seaweedfs): docker logs stargate-seaweedfs --tail 50.

6. VM-Ressourcen¶

free -h                              # memory (min 8 GB)
nproc                                # CPUs (min 4)
docker stats --no-stream             # per-container CPU/RAM
uptime                               # load average

Host-Metriken werden zudem für Prometheus unter :9100/metrics exportiert (siehe Überwachung). Wenn der Host swappt oder voll ausgelastet ist, müssen Sie mit schwankenden Health Checks und langsamen Updates rechnen.

7. Netzwerk und Ports¶

Schnelle Erreichbarkeitsprüfung der wichtigsten eingehenden Ports:

for p in 25 443 8180 8190 19818; do nc -zv <this-server-ip> $p; done

Port	Dienst	Richtung
`25`	Stalwart SMTP (eingehende E-Mails)	eingehend
`443`	Dashboard (HTTPS)	eingehend
`8180`	Keycloak	eingehend
`8190`	Dozzle (optional)	eingehend
`19818`	WireGuard (UDP und TCP)	ein- und ausgehend

Ausgehender Zugriff ist erforderlich auf die Container-Registry, die S/MIME-Zertifizierungsstelle (über den WireGuard-Tunnel) und jede von Ihnen konfigurierte Remote-Loki-Instanz. Die vollständige Port-Tabelle finden Sie auf der Startseite und in der Anwendungsübersicht.

Das Docker-Netzwerk überschneidet sich mit dem lokalen Netzwerk¶

Die Dienste kommunizieren über ein internes Docker-Netzwerk. Docker wählt dessen Adressbereich beim Erstellen des Stacks und meidet dabei die Netzwerke, mit denen die VM in diesem Moment direkt verbunden ist. Enthält der Bereich trotzdem Adressen aus Ihrem Netzwerk, kann die Appliance diese Rechner nicht erreichen (zum Beispiel einen Mail- oder DNS-Server), und diese erreichen die Appliance nicht. Der Health Check meldet das unter Docker network:

[FAIL] stargate-network 172.18.0.0/16 overlaps host routes: 172.18.5.0/24 dev ens18 - see Troubleshooting: The Docker network overlaps the local network

Die IP-Adresse wurde nach dem ersten Start geändert: Docker hat den Bereich gewählt, als die VM noch ihre erste Adresse hatte. Auf einem Gateway ohne Onboarding verwenden Sie Purge und Neuinstallation aus Server-IP-Adresse ändern oben; Docker wählt dann selbst einen freien Bereich. Auf einem Gateway mit abgeschlossenem Onboarding erstellen Sie das Netzwerk wie unten beschrieben neu.
Das überschneidende Netzwerk liegt hinter einem Router (eine statische Route oder ein Netzwerk an einem anderen Standort): Docker meidet solche Netzwerke nicht. Der Health Check sieht jede Route auf dem Host, aber keine Netzwerke, die über das Standard-Gateway erreicht werden. Geben Sie Docker zuerst einen freien Bereich: Ergänzen Sie /etc/docker/daemon.json wie folgt, behalten Sie vorhandene Einstellungen bei und verwenden Sie einen Bereich, den Ihr Netzwerk nicht nutzt:
```
{
  "default-address-pools": [
    { "base": "10.200.0.0/16", "size": 24 }
  ]
}
```
Führen Sie danach systemctl restart docker aus und erstellen Sie das Netzwerk wie unten beschrieben neu.

Beim Neuerstellen des Netzwerks bleiben alle Daten in /var/data erhalten. Stoppen Sie zuerst den Dienst, sonst hält ein laufendes Dozzle das alte Netzwerk belegt:

systemctl stop stargate
cd /usr/share/stargate-deployment/docker-compose
docker compose --env-file /var/data/vereign/.env down
systemctl start stargate
/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh

8. Wiederherstellungsmassnahmen¶

Geordnet vom geringsten bis zum stärksten Eingriff:

docker compose up -d <service>       # recreate one stuck service
sudo systemctl restart stargate      # restart the whole stack (via start.sh)
/usr/share/stargate-deployment/docker-compose/scripts/stop.sh  &&  /usr/share/stargate-deployment/docker-compose/scripts/start.sh

Backups und destruktive Wiederherstellung

/usr/share/stargate-deployment/docker-compose/scripts/backup.sh und /usr/share/stargate-deployment/docker-compose/scripts/restore.sh übernehmen die Datensicherung und -wiederherstellung. /usr/share/stargate-deployment/docker-compose/scripts/purge.sh löscht alle Daten (Datenbanken, Vault, Speicher) für eine saubere Neuinstallation. Verwenden Sie das Skript nur als letztes Mittel und nur mit einem aktuellen Backup. Details: Docker erweiterte Konfiguration.

9. Wann Sie sich an den Support wenden sollten¶

Zeigt der Health Check nach den obigen Schritten weiterhin Fehler an, eröffnen Sie ein Ticket über Support / Kontakt und fügen Sie Folgendes bei:

Die Appliance-Version (/usr/share/stargate-deployment/docker-compose/scripts/gather-app-versions.sh) und den Kundennamen.
Die Ausgabe des Health Checks (/usr/share/stargate-deployment/docker-compose/scripts/health-check.sh -v).
Einen Link zum Log-Paket aus /usr/share/stargate-deployment/docker-compose/scripts/send-logs-to-support.sh (siehe Logs an den Support senden).
Was Sie gerade getan haben, als das Problem auftrat, sowie allfällige Screenshots.

Keycloak nach dem Update einrichten¶

Hinweis: Diese Anleitung gilt, wenn Sie das VM-Image v0.5.1 verwendet und anschliessend auf eine neuere Version aktualisiert haben.

Nach dem letzten Keycloak-Update führt eine inkompatible Änderung (Breaking Change) dazu, dass authentifizierte Benutzerinnen und Benutzer beim Aufrufen bestimmter Anwendungsrouten (z. B. Peers, Peer Certificates) unerwartet auf die Anmeldeseite umgeleitet werden.

Zur Behebung muss die folgende manuelle Konfiguration in der Keycloak-Oberfläche vorgenommen werden.

Lösungsschritte¶

Öffnen Sie Keycloak im Browser unter https://<VM IP address>:8180/admin/master/console/
- Der Port :8180 ist zwingend: Keycloak wird auf Port 8180 bereitgestellt. Wenn Sie die IP-Adresse ohne Port öffnen, landen Sie stattdessen beim Dashboard (:443), das Sie zur Anmeldung im Realm stargate weiterleitet, in dem der Admin-Benutzer nicht existiert (die übliche Ursache für «invalid username or password» bzw. «falscher Realm» an dieser Stelle).
- Melden Sie sich im Realm master an (der Pfad /admin/master/console/ wählt ihn aus), mit dem Benutzernamen admin (dem Wert von KEYCLOAK_ADMIN_USER, in Kleinbuchstaben) und dem Wert von KEYCLOAK_ADMIN_PASSWORD aus der Datei /var/data/vereign/.env der Maschine (auslesbar über die Linux-Konsole).
Wechseln Sie in der Admin-Konsole über die Realm-Auswahl (oben links) von master zu stargate.
Öffnen Sie Clients → dashboard.
Wechseln Sie zur Registerkarte Client scopes → klicken Sie auf dashboard-dedicated.
Wählen Sie Configure a new mapper → Audience.
Nehmen Sie folgende Einstellungen vor:
- Name: apisix-audience
- Included client audience: apisix (aus der Dropdown-Liste auswählen)
- Included custom audience: (leer lassen)
- Add to access token: On
- Add to token introspection: On
- Add to ID token / lightweight token: Off
Klicken Sie auf Save.

Passwort eines Stargate-Benutzers in Keycloak zurücksetzen¶

Mit den folgenden Schritten setzen Sie das Passwort eines Stargate-Benutzers über die Keycloak-Administrationskonsole zurück.

Mit der HIN Gateway-VM verbinden
- Öffnen Sie die VM-Konsole oder verbinden Sie sich per SSH mit der HIN Gateway-VM.
Zugangsdaten des Keycloak-Administrators abrufen
- Öffnen Sie die Datei /var/data/vereign/.env.
- Suchen Sie die folgenden Variablen:
  - KEYCLOAK_ADMIN_USER
  - KEYCLOAK_ADMIN_PASSWORD
Keycloak-Administrationskonsole öffnen
- Rufen Sie im Browser folgende Adresse auf: http://<VM-IP>:8180/admin/master/console
- Ersetzen Sie <VM-IP> durch die IP-Adresse der HIN Gateway-VM.
Bei Keycloak anmelden
- Geben Sie den Benutzernamen und das Passwort des Administrators aus der .env-Datei ein.
- Behalten Sie das Administratorpasswort unverändert bei. Wenn Sie es dennoch ändern, müssen Sie das neue Passwort sicher aufbewahren.
Realm Stargate auswählen
- Wählen Sie in der Realm-Auswahl der Keycloak-Administrationskonsole Stargate aus.
Benutzer suchen
- Öffnen Sie Users.
- Suchen Sie den Stargate-Benutzer, dessen Passwort zurückgesetzt werden soll, und wählen Sie ihn aus.
Passwort des Benutzers zurücksetzen
- Wählen Sie die Option zum Zurücksetzen des Passworts.
- Geben Sie das neue Passwort ein und bestätigen Sie die Änderung.

Ändern oder setzen Sie im Rahmen dieses Vorgangs nicht das Passwort des Keycloak-Administrators zurück. Jede Änderung des Admin-Passworts kann dazu führen, dass Keycloak gesperrt wird und niemand mehr darauf zugreifen kann.

Aktivierungscode anfordern¶

Wenn Sie eine HIN Gateway-Instanz installieren oder neu installieren möchten, benötigen Sie einen Aktivierungscode, den Sie beim HIN Support erhalten.

Das Zurücksetzen des Aktivierungscodes trennt die Peer-Verbindung

Wird der Aktivierungscode einer aktiven Instanz zurückgesetzt, wird die WireGuard-Peer-Verbindung des Kunden gelöscht.

Beantragen Sie das Zurücksetzen für die falsche Kundeninstanz, wird die Verbindung dieser aktiven Instanz gelöscht und unterbrochen. Prüfen Sie deshalb vor der Anfrage genau, um welche Instanz es sich handelt, und bestätigen Sie alle darauf gehosteten Domains.

Neustart auf VM v0.6.1¶

Bitte beachten Sie: Wenn Sie eine Instanz, die auf v0.6.1 läuft, neu starten (REBOOT), wird sie auf die vorherige, nicht funktionierende Stalwart-Version <0.0.23 zurückgesetzt.

Wir empfehlen, die Instanz im Bereich Settings->System version auf eine neuere Version zu aktualisieren!