Docker warten und Fehler beheben

Docker: experimentell, im Wartungsmodus

Die Docker-Version ist funktionsfähig, aber möglicherweise noch instabil. Sie ist experimentell und befindet sich im Wartungsmodus: Es gibt nur noch Fehler- und Sicherheitskorrekturen, keine neuen Funktionen.

Aktualisieren

1. Sichere zuerst /config und deine Modellordner wie unten beschrieben.
2. Wähle in .env den gewünschten IMAGE_TAG. Eine feste Version bleibt fest; auch die Release-Compose-Datei folgt ohne Überschreibung ihrer Release-Version.
3. Lade das Image und erstelle den Container neu:

docker compose pull
docker compose up -d
docker compose ps
docker inspect --format '{{.State.Health.Status}}' "$(docker compose ps -q 3mf-katalog)"

4. Prüfe die Versionsanzeige in der App und öffne die Begleitseite und den Browser-Desktop.

pull allein ersetzt keinen laufenden Container. Bei der Repository-Datei kannst du up -d --no-build verwenden, um einen lokalen Build auszuschließen. Für eigene Builds setzt du die neue passende APP_URL und APP_VERSION, führst docker compose build und anschließend docker compose up -d --no-build aus.

Tag	Bedeutung im Image-Workflow
X.Y.Z	Konkrete stabile Release-Version.
X.Y	Höchste veröffentlichte stabile Version dieser Reihe.
latest	Höchste veröffentlichte stabile Version; entsteht erst mit einem stabilen Image-Release.
0.16.0	Konkrete stabile Version ohne v; bleibt unverändert. Vorabversionen haben einen Zusatz wie 0.16.0-12.
rc	Beweglicher Tag, den ein veröffentlichender RC-Workflow setzt; verändert latest nicht.

Verwende getrennte Compose-Projekte und /config-Ordner für Stable und RC. Bei parallelem Betrieb brauchst du unterschiedliche Host-Ports. Eine automatische Übernahme von RC nach Stable ist nicht eingerichtet. Ein älteres Image kann ein neueres Datenbankschema möglicherweise nicht lesen; bewahre die Sicherung vor dem Update auf.

Vollständige Sicherung

Sichere den ganzen Host-Ordner für /config, nicht nur catalog.db. Dazu gehören App-Einstellungen, Papierkorb, WebView-Daten, die gespeicherte Passwortdatei, der Signaturschlüssel .katalog-web-secret und die Ausblendliste .katalog-web-hidden.json. Die Begleitseite sucht die Datenbank standardmäßig unter /config/.local/share/*/catalog.db. Sichere außerdem /models, alle weiteren Modell-Mounts sowie deine Compose-Datei und .env. Halte Sicherungen mit Zugangsdaten privat.

1. Stoppe den Container vor einer Dateikopie:

docker compose stop

2. Kopiere den vollständigen Host-Ordner config einschließlich versteckter Dateien und alle Modellordner mit deinem Sicherungswerkzeug. Erhalte Besitzer und Rechte. Sichere abweichende Mount-Quellen an ihrem tatsächlichen Ort.
3. Starte danach wieder:

docker compose up -d

Für eine Wiederherstellung stoppe den Container, spiele die zusammengehörigen gesicherten Ordner mit passenden Rechten zurück und behalte dieselben Containerpfade bei. Starte mit der zur Sicherung passenden Image-Version und prüfe Katalog und Dateien.

Die ZIP-Sicherung in der App enthält nur catalog.db und settings.json, keine Modelle und keinen Papierkorb. Sie ersetzt daher keine vollständige Sicherung der Mounts. Nach einem App-Backup-Import musst du Druckerverbindungen wieder aktivieren; der Import pausiert sie.

Logs und Neustarts

docker compose logs --tail=100 3mf-katalog
docker compose logs -f 3mf-katalog

App-Ausgaben und Neustartmeldungen stehen im Container-Log. Beende die laufende Log-Anzeige mit Strg+C. Entferne Passwörter und private Angaben, bevor du Logs weitergibst: Beim ersten Start kann das erzeugte Passwort darin stehen.

Der App-Dienst startet eine beendete App erneut. Bei schnellen Abstürzen wächst die Wartezeit von 2 bis auf 30 Sekunden; nach mindestens 60 Sekunden Laufzeit wird sie zurückgesetzt. Compose gewährt beim Stoppen 30 Sekunden zum Schließen von SQLite/WAL. docker compose down entfernt Container und Netz, erhält aber die eingebundenen Host-Ordner.

Fehlersuche

Container startet nicht oder die App startet ständig neu

1. Prüfe docker compose ps und die Logs.
2. Prüfe den Tag: Es muss ein veröffentlichter Tag sein, zum Beispiel latest (neueste stabile Version) oder eine feste Version wie 0.16.0.
3. Prüfe Zugangsdaten auf ungültige Zeichen, Mount-Rechte und freien Speicher. Bei lokalen Builds müssen APP_URL und APP_VERSION gesetzt sein.
4. Öffne nach einem Neustart den Browser-Desktop. Ein gesunder Healthcheck bestätigt nur App-Prozess und HTTP-Erreichbarkeit, nicht jede GUI-Funktion.

Passwort vergessen

Lies bei erzeugten Passwörtern config/.kasmvnc-password mit einem berechtigten Benutzer. Alternativ setze ein gültiges eigenes PASSWORD in .env und erstelle den Container mit docker compose up -d neu.

Für ein neues Zufallspasswort stoppe den Container, entferne gezielt config/.kasmvnc-password, lasse PASSWORD leer und starte wieder. Das neue Passwort erscheint im Log. Eine beschädigte gespeicherte Datei wird nicht automatisch ersetzt; erlaubt sind genau 48 kleine Hex-Zeichen mit optionalem abschließendem Zeilenumbruch. Ein eigenes Passwort ersetzt die alte Datei nicht.

Rechte, fehlende Modelle oder deaktivierter Upload

Prüfe Host-Quellen, PUID/PGID, NAS-ACLs und Schreib-/Suchrechte. Für Uploads darf der Modell-Mount nicht schreibgeschützt (:ro) sein. KATALOG_UPLOAD_DIR muss innerhalb einer erlaubten Wurzel liegen. Prüfe bei fehlenden Download-Knöpfen, ob die Datei existiert und unter einer erlaubten Wurzel liegt. Bei leerer Begleitseite richte zuerst den Katalog ein; prüfe danach Datenbankpfad und Leserechte.

Netzwerk- oder FUSE-Dateisystem unter /config

Der Start warnt bei erkannten Netzwerk-/FUSE-Dateisystemen und legt /config/.network-filesystem-warning an. Die App zeigt dazu einen schließbaren Hinweis. SQLite braucht lokalen Speicher; andernfalls kann die Datenbank beschädigt werden. Sichere die Daten bei gestopptem Container und verlege /config auf ein lokales Volume. /models darf auf einer NAS-Freigabe bleiben. Die Dateisystemerkennung ist eine Warnhilfe, keine Garantie für korrekte Speichersperren.

Docker in Proxmox-LXC

Die Docker-README nennt nesting=1 und keyctl=1 aus einem Testerbericht für Docker in Proxmox-LXC. Das ist kein nachgewiesener Test dieser Umgebung durch das Projekt. Behandle es als Hinweis zur Fehlersuche, nicht als zugesicherte Installationsanleitung.

Was „möglicherweise instabil“ bedeutet

Die Docker-README nennt noch ausstehende Tests für die 3D-Vorschau mit vielen Modellen, Wiederherstellung mit Papierkorbdateien und Betrieb in LXC. arm64 ist nicht unterstützt. Software-Rendering sowie Unterschiede bei Zwischenablage, Tastatur, Dateidialogen und WebKit bleiben Grenzen. Die CI-Skripte prüfen unter anderem Start, Anmeldung, Neustart und signierte Downloads; das ersetzt keinen vollständigen Bedienungs- und Wiederherstellungstest auf deinem Server.

Fehler melden

Nutze „Fehler melden“ in der App, GitHub Issues oder Discord. Beschreibe Image-Version, Host-System, Browser, die Schritte zum Fehler und relevante bereinigte Logs. Teile keine Passwörter oder signierten Download-Adressen. Weitere Hinweise zur Fehlermeldung.