Docker installieren

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.

1. Compose-Datei auswählen

Empfohlen ist die fertige docker-compose.yml aus der Dateiliste des gewünschten Releases. Damit brauchst du das Repository nicht zu klonen. Diese Datei verwendet nur image:, kein build:, und setzt ohne Überschreibung die Version dieses Releases ein.

Welche Release-Datei?

Fehlt docker-compose.yml in der Dateiliste eines älteren Releases, verwende den Repository-Weg weiter unten. Für stabile Releases funktioniert der direkte Download der Compose-Datei. Für Vorabversionen öffnest du die Dateiliste des jeweiligen Releases. Der Link zum neuesten stabilen Release wählt keine Vorabversion aus.

1. Lege auf dem Server einen eigenen Ordner für den Container an.
2. Speichere die heruntergeladene Datei dort als docker-compose.yml.
3. Öffne ein Terminal in diesem Ordner. Alle folgenden Compose-Befehle führst du dort aus.

Alternative: Dateien aus dem Repository

Verwende den vollständigen Ordner docker/ aus dem Repository und wechsle hinein. Kopiere .env.example nach .env:

cp .env.example .env

Diese Compose-Datei enthält auch einen build:-Abschnitt. Für das veröffentlichte Image verwendest du ausdrücklich:

docker compose pull
docker compose up -d --no-build

Wähle vorher den Tag und die Einstellungen wie nachfolgend beschrieben. Für einen eigenen Build brauchst du zusätzlich APP_URL als HTTPS-Adresse der Linux-x86_64-AppImage und die passende APP_VERSION. Trage jeweils nur den Wert hinter = ein. Danach:

docker compose build
docker compose up -d --no-build

BASE_IMAGE ist nur für diesen lokalen Build relevant; Vorgabe: ghcr.io/linuxserver/baseimage-selkies:ubuntunoble (per Digest festgelegt).

2. Ordner und Rechte vorbereiten

mkdir -p config models
id -u
id -g

./config wird als /config eingebunden und muss auf lokalem Speicher liegen. ./models wird als /models eingebunden. Trage die ermittelten IDs als PUID und PGID ein. Die Host-Ordner müssen für diese IDs lesbar, durchsuchbar und zum Schreiben geeignet sein; prüfe auf dem NAS auch die ACLs. CUSTOM_USER ist nur der Browser-Login und ändert die Dateirechte nicht.

MODELS_DIR kann einen anderen Host-Ordner wählen. Behalte die Containerpfade dauerhaft bei: Der Katalog speichert absolute Pfade. Für eine weitere Bibliothek aktivierst du in Compose beispielsweise einen Mount nach /models2.

3. .env einrichten

Lege bei der Release-Datei selbst eine .env neben docker-compose.yml an. Beispiel mit der festen Version 0.16.0:

IMAGE_TAG=0.16.0
PUID=1000
PGID=1000
TZ=Europe/Berlin
UMASK=022
MODELS_DIR=./models
CUSTOM_USER=abc
PASSWORD=
ALLOW_NO_AUTH=false

Passe IDs und Pfade an. Lässt du bei der Release-Datei IMAGE_TAG weg, bleibt die Release-Version voreingestellt. Das Repository-Beispiel verwendet dagegen latest. Eine feste Version wie 0.16.0 (ohne v) bleibt, wie sie ist; latest folgt der jeweils neuesten stabilen Version.

Variable	Bedeutung und Vorgabe
IMAGE_TAG	Image-Version; Repository: latest, Release-Datei: Version des Releases. rc folgt den veröffentlichten Vorabversionen (RC-Images), falls es gerade eine gibt.
PUID, PGID	IDs des App-Benutzers auf dem Host; jeweils 1000.
TZ	Zeitzone; Europe/Berlin.
UMASK	Dateirechte-Maske; 022. Für gemeinsame Gruppen kommt 002 infrage. Die Passwortdatei bleibt auf 600.
MODELS_DIR	Host-Quelle für /models; ./models.
CUSTOM_USER	Browser-Benutzername; abc.
PASSWORD	Leer: Passwort erzeugen oder gespeichertes wiederverwenden. Sonst eigenes Passwort.
ALLOW_NO_AUTH	false; exakt true deaktiviert die Anmeldung, auch bei gesetztem Passwort.
KATALOG_PUBLIC_URL	Optional: feste Browser-Adresse ohne abschließenden Slash. Sonst wird sie beim Besuch der Begleitseite ermittelt.
KATALOG_UPLOAD_DIR	Optional: Upload-Ziel; /models/Eingang.
KATALOG_UPLOAD_MAX_MB	Optional: positive ganze Zahl in MiB pro Datei; 2048. Wegen nginx höchstens 4096 verwenden.
APP_URL, APP_VERSION	Nur lokaler Build; beide im Repository-Beispiel leer, für den Build erforderlich.
BASE_IMAGE	Nur lokaler Build; Vorgabe siehe oben.

Die drei optionalen KATALOG_-Variablen müssen auch unter environment: in Compose aktiviert sein. Nur ein Eintrag in .env reicht nicht. Leere Upload-Werte verwenden die Dienstvorgaben. Details stehen unter Bedienung.

chmod 600 .env

Regeln für Zugangsdaten

CUSTOM_USER erlaubt nur A-Z, a-z, 0-9, Punkt, Unterstrich und Minus, aber kein führendes Minus. PASSWORD darf nicht mit Minus beginnen und keine Leerzeichen, Tabs, Zeilenumbrüche oder diese Zeichen enthalten: *, ?, [, :, %, \.

Für selbst gesetzte Werte prüft der Container keine Mindest- oder Höchstlänge. Ein erzeugtes Passwort hat exakt 48 kleingeschriebene Hex-Zeichen. Leere Werte verwenden die Vorgaben. Ungültige Zeichen verhindern den Start auch bei ALLOW_NO_AUTH=true.

Lass die Anmeldung im Heimnetz eingeschaltet. ALLOW_NO_AUTH=true gibt den Zugang ohne Anmeldung frei und erzeugt eine Warnung im Log.

4. Starten und anmelden

Für die Release-Datei:

docker compose pull
docker compose up -d
docker compose ps
docker compose logs 3mf-katalog

1. Öffne http://127.0.0.1:3000 auf dem Docker-Host. Port 3001 bietet HTTPS des Basisimages.
2. Melde dich mit CUSTOM_USER (Vorgabe abc) und deinem Passwort an.
3. Bei leerem PASSWORD steht das erzeugte Passwort nur beim ersten Erzeugen im Log. Du findest es außerdem unter config/.kasmvnc-password:

cat config/.kasmvnc-password

Die Datei hat Rechte 600; verwende einen dazu berechtigten Host-Benutzer. Später wird das Passwort wiederverwendet. Ein eigenes PASSWORD ersetzt die gespeicherte Zufallsdatei nicht; entfernst du die Variable wieder, gilt das gespeicherte Passwort. Ein eigenes Passwort ist über die Container-Umgebung in docker inspect sichtbar. Schütze .env, Passwortdatei und die Logs des ersten Starts.

5. Heimnetz und Reverse Proxy

Die Vorgabe bindet beide Ports nur an 127.0.0.1 des Hosts. Für Zugriff von anderen Geräten ersetze diese Adresse durch die tatsächliche LAN-IP deines Servers, beispielsweise:

ports:
  - "192.168.1.10:3000:3000"
  - "192.168.1.10:3001:3001"

Erzeuge den Container mit docker compose up -d neu und öffne beispielsweise http://192.168.1.10:3000. Verwende deine tatsächliche Adresse. Die Anmeldung bleibt aktiv.

Ein Reverse Proxy muss den öffentlichen Host einschließlich Port und X-Forwarded-Proto weiterreichen und WebSockets unterstützen. Bei Nginx Proxy Manager nennt die Docker-README die Option „Websockets“. Nutze für externen Zugriff TLS mit gültigem Zertifikat und behalte den Login-Schutz. Veröffentliche die internen Ports 8082 und 8099 nicht am Host. Für Uploads sind zusätzlich Größenlimit und Streaming relevant.

6. Funktion prüfen

docker compose ps
docker inspect --format '{{.State.Health.Status}}' "$(docker compose ps -q 3mf-katalog)"
docker compose logs --tail=100 3mf-katalog

Der Healthcheck hat 120 Sekunden Startfrist und läuft danach alle 30 Sekunden. Er prüft einen lebenden App-Prozess und HTTP-Status 200 oder 401 auf Port 3000. Er beweist keine vollständige Bedienbarkeit der Oberfläche. Prüfe deshalb zusätzlich die App und /katalog/ im Browser. Weiter zur Bedienung.