Fehlerbehebung

Irgendwas klappt nicht? Hier stehen die Probleme, über die man am häufigsten stolpert, und wie du wieder herauskommst.

Mit der Diagnose anfangen

Bevor du woanders suchst, öffne Einstellungen → Diagnose. Sie prüft deine ganze Einrichtung und sagt dir zu jedem Befund, was sie angeschaut hat, was dabei herauskam und wie du es behebst. Geprüft werden Docker-Engine, wo /config liegt, Host-Pfade, Speicherplatz, Backup-Verzeichnis, Datenbank-Integrität, der Host für Projekt-Links, Proxy-Ports, Wildcard-DNS, SSH, HTTPS, Version, ob Projekte und Docker zusammenpassen, und die Benachrichtigungen. Befunde mit einem Knopf behebst du direkt dort. Solange es Warnungen oder Fehler gibt, stehen sie oben auf dem Dashboard. Aus einer Shell gibt envoryx diagnostics dasselbe aus (siehe Kommandozeile); ist etwas kaputt, endet es mit Exit-Code 1, du kannst es also in einen Monitoring-Job stecken.

Wildcard-DNS wird zweimal geprüft, und es hilft zu wissen, warum. Die Prüfung aus deinem Browser ist die, auf die es ankommt - sie zeigt nebenbei auch, dass dein Gerät der CA vertraut. Die zweite läuft im Envoryx-Container, und der nutzt oft einen anderen DNS-Server. Die beiden können sich also widersprechen. Die zweite Prüfung vergleicht die Antwort mit dem Host für Projekt-Links. Hast du keinen eingetragen, fragt sie die Adresse, auf die der Name zeigt, nach einem Test-Host und meldet nur dann OK, wenn dort der Proxy dieser Instanz antwortet. Antwortet ein anderer Server, gibt es eine Warnung; kommt gar keine Antwort, bleibt das Ergebnis unbestätigt.

„Host-Pfade konnten nicht erkannt werden“

Projektcontainer bekommen deine Dateien per Bind-Mount, und die löst der Docker-Daemon auf dem Host auf, nicht in Envoryx. Envoryx muss also wissen, welche Host-Ordner hinter /projects und /config stecken; das findet es heraus, indem es seinen eigenen Container anschaut. Klappt das nicht, zeigt das Dashboard einen roten Hinweis, und du kannst keine Projekte anlegen, bis du es ihm selbst sagst:

ENVORYX_PROJECTS_HOST_PATH=/srv/envoryx/projects
ENVORYX_CONFIG_HOST_PATH=/srv/envoryx/config

Unter Unraid nimmst du immer dieselben /mnt/user/…-Pfade (oder /mnt/cache/…), die du auch in den Volume-Zuordnungen verwendet hast.

Envoryx startet nicht: Netzwerk-Dateisystem

In /config liegt eine SQLite-Datenbank, und SQLite braucht Dateisperren, die wirklich funktionieren. Auf NFS, SMB/CIFS, 9p oder Ceph tun sie das oft nicht, und die Datenbank würde kaputtgehen, ohne dass es jemand merkt. Deshalb startet Envoryx dort gar nicht erst. Nimm einen lokalen Ordner. ENVORYX_ALLOW_NETWORK_FS=true schaltet die Prüfung ab - auf eigenes Risiko.

Unter Unraid funktioniert /mnt/user/… (FUSE), zeigt aber eine Warnung; /mnt/cache/appdata/envoryx oder Exclusive access für den Appdata-Share ist die sicherere Wahl.

Projekt-Links zeigen auf die falsche Adresse

Webserver der Projekte, Mailpit, Datenbank-Ports und Objektspeicher veröffentlichen ihre Ports auf dem Docker-Host, und Envoryx baut seine Links aus der Adresse in deinem Browser. Erreichst du Envoryx unter einer anderen Adresse als den Docker-Host - weil es eine eigene IP auf br0/macvlan hat oder hinter einem Reverse-Proxy steht -, zeigen die Links ins Leere. Stell den richtigen Host unter Einstellungen → Domains & HTTPS → Projekt-Links & Entwicklerrechner ein (oder per ENVORYX_PUBLIC_HOST). Merkt Envoryx, dass es eine eigene IP hat, bietet es dir den Docker-Host mit einem Klick an.

https://shop.test öffnet sich nicht

Meistens ist es eines von vier Dingen:

• Der Name löst nicht auf - der Wildcard-DNS-Eintrag fehlt oder zeigt auf die falsche Adresse; siehe Domains & HTTPS. Hat Envoryx eine eigene IP, muss der Eintrag auf diese zeigen.
• Zertifikatswarnung - die lokale CA ist auf diesem Gerät noch nicht installiert (Firefox hat einen eigenen Speicher und braucht sie extra).
• Kein Proxy-Port - 80/443 sind nicht veröffentlicht; Einstellungen → Domains & HTTPS warnt dich davor.
• Eine 502-Seite - der Anwendungsserver des Projekts lauscht noch nicht. Seine Logs verraten dir den Grund: Zeilen mit envoryx: waiting for … sagen, worauf er wartet.

Stoppen dauert zu lange, Operationen „unterbrochen“

Stoppt Envoryx, gibt es laufenden Operationen ENVORYX_SHUTDOWN_GRACE Zeit (standardmäßig 8 s). Das muss unter dem Stopp-Timeout des Containers bleiben, sonst beendet Docker den Prozess vorher. Der docker run-Befehl und die Compose-Datei der Installationsseite setzen 90 s Stopp-Timeout mit ENVORYX_SHUTDOWN_GRACE: 80s. Unter Unraid ist das Stopp-Timeout eine globale Einstellung (Settings → Docker → Docker stop timeout); erhöhe es zusammen mit Shutdown grace im Template.

Eine Operation, die ein Neustart abgeschnitten hat, ist als durch einen Envoryx-Neustart unterbrochen markiert. Führ sie einfach noch einmal aus.

Projekt anlegen schlägt fehl: kein Adressbereich mehr frei

Jedes Projekt hat sein eigenes Docker-Netz und behält es auch, wenn es gestoppt ist. Envoryx gibt jedem neuen Netz ein /24 aus ENVORYX_NETWORK_POOL (10.213.0.0/16, wenn du nichts setzt), das reicht für 256 Projekte. Sind alle vergeben, schlägt das Anlegen des nächsten Projekts fehl und sagt das auch: Lösch Projekte, die du nicht mehr brauchst, oder gib dem Pool einen größeren Bereich. Wird 10.213.0.0/16 in deinem LAN oder VPN schon benutzt, setz am Envoryx-Container einen anderen Bereich; bestehende Netze behalten ihren. Mit off wählt wieder Docker die Bereiche, und dessen Standard ist nach etwa 30 Netzen erschöpft.

Ein Projekt startet nicht: Host-Port belegt

Envoryx vergibt Host-Ports zwischen ENVORYX_PORT_RANGE_START und _END (20000 bis 20999, solange du nichts anderes setzt) und überspringt die, die schon belegt sind: von anderen Projekten, von Docker-Containern und von Programmen direkt auf dem Docker-Host, etwa einer JetBrains-IDE oder einer dort installierten Datenbank. Die letzten sieht es über einen kurzlebigen busybox-Container im Host-Netzwerk. Schnappt sich ein Programm den Port erst später, während das Projekt gestoppt ist, zieht das Projekt beim nächsten Start auf einen freien HTTP-Port um; über seine .test-Adresse erreichst du es so oder so, nur der direkte Port ändert sich. Bei jedem anderen Port bricht der Start mit host port in use ab und nennt den Port: Beende das Programm, das ihn hält, oder schalte die Veröffentlichung dieses Ports auf der Karte, auf der du sie eingeschaltet hast, aus und wieder ein, dann bekommt er einen freien.

Verwaiste Container und Volumes

Manchmal trägt ein Container, Netz oder Volume die Labels von Envoryx, aber das Projekt dazu gibt es nicht mehr - nach dem Einspielen eines älteren Instanz-Backups oder einem Löschen, das nicht fertig wurde. Dann ist es verwaist. Verwaiste Container und Netze entfernt Envoryx nach etwa einer Minute selbst. Bei Volumes ist das anders: Darin stecken Daten, deshalb entfernt Envoryx sie nie von sich aus. Sie bleiben auf der Seite Docker mit einem Knopf Entfernen, bis du entscheidest. Legst du unter demselben Namen wieder ein Projekt an, übernimmt es seine alten Volumes. Aus einer Shell listet envoryx docker orphans sie auf, und envoryx docker remove volume <name> --yes entfernt eines (siehe Kommandozeile).

Dieses automatische Aufräumen gilt nur für das, was diese Instanz selbst gelabelt hat. Verwaiste Ressourcen ohne Instanz-Label stammen von einem Envoryx vor 0.18, und sie können genauso gut einer anderen Instanz auf demselben Host gehören. Die Seite Docker markiert sie mit älteres Envoryx, und sie bleiben, bis du sie dort entfernst. Hinterlassenschaften dieser Instanz sind sie nicht, deshalb zählen sie auch nicht als ihre verwaisten Ressourcen: Das Dashboard lässt sie bei seiner Zahl weg, und Projekte vs. Docker in der Diagnose erwähnt sie ohne Warnung. Die gibt es nur für die verwaisten Ressourcen dieser Instanz.

Ein geleertes /config ist eine andere Geschichte. Der frische Start legt eine neue Instanz-ID an, die alten Projekt-Container sind also gar nicht verwaist, sondern gehören einer anderen Instanz: Envoryx lässt sie in Ruhe, und ein wiederhergestelltes Projekt, das seine alten Namen haben will, scheitert mit der Name gehört einer anderen Envoryx-Instanz auf diesem Docker-Host. Spielst du das Instanz-Backup ein, übernimmt Envoryx die alte ID von selbst, solange kein anderer Envoryx-Container auf dem Host ist. Gibt es einen, machst du es von Hand: Lies die alte ID aus dem Label envoryx.instance eines Containers, stopp Envoryx, schreib sie nach /config/instance-id und starte Envoryx wieder.

docker inspect -f '{{ index .Config.Labels "envoryx.instance" }}' <ein Projekt-Container>

Zugang verloren

Passwort vergessen oder anderweitig ausgesperrt? Die Zugangsdaten setzt du aus einer Shell im laufenden Container zurück, und sonst wird nichts angefasst:

docker exec -it envoryx envoryx admin users            # welche Konten es gibt
docker exec -it envoryx envoryx admin reset-password   # neues Passwort, einmal ausgegeben
docker exec -it envoryx envoryx admin reset-password --user alex --password 'mein neues Passwort'
docker exec -it envoryx envoryx admin logout-all       # alle Browser-Sitzungen beenden
docker exec -it envoryx envoryx admin revoke-tokens    # alle API-Tokens löschen
docker exec -it envoryx envoryx admin revoke-token ci  # nur einen, per Name, ID oder Präfix
docker exec -it envoryx envoryx admin reset --yes      # alle Konten entfernen → die Einrichtungsseite erscheint wieder

reset löscht Konten, Sitzungen und API-Tokens, lässt aber Projekte, Einstellungen und Backups in Ruhe. Unter Unraid ist die Konsole des Containers (Docker → Envoryx → Console) dieselbe Shell. Und hast du gerade ein paar falsche Passwörter probiert: Fehlgeschlagene Anmeldungen werden bis zu 15 Minuten gebremst, gib ihm also einen Moment.

Health-Endpunkt

GET /api/v1/health antwortet ohne Anmeldung. Er schlägt nur fehl (503), wenn die Datenbank unbrauchbar ist. Eine nicht erreichbare Docker-Engine meldet er als "docker": false mit dem Status degraded, antwortet aber weiter mit 200 - sonst würden Auto-Heal-Werkzeuge Envoryx in einer Schleife neu starten, solange Docker weg ist.