Wer Dateien auf einem Server oder NAS über den Browser verwalten will, ohne gleich eine komplette Cloud-Suite wie Nextcloud zu betreiben, landet schnell bei einem schlanken webbasierten Dateimanager. FileBrowser Quantum ist so ein Werkzeug: ein einzelner Container, der ein oder mehrere Verzeichnisse als Weboberfläche mit Benutzerverwaltung, Suche, Vorschau und Freigabelinks bereitstellt. Das Projekt ist ein umfangreicher Fork des klassischen File Browser und wird aktiv weiterentwickelt.

Diese Anleitung zeigt den kompletten Weg mit Docker Compose: compose.yaml, config.yaml, Erstkonfiguration, Healthcheck, Rechte, Reverse Proxy, Backup und Restore, Updates und Deinstallation. Alle als getestet markierten Schritte wurden am 25.09.2026 in einer isolierten Testumgebung auf einem Linux-Host mit Docker ausgeführt. Der wichtigste Praxisfund: Die Umgebungsvariable FILEBROWSER_ADMIN_PASSWORD setzt das Admin-Passwort bei jedem Containerstart zurück. Wer das Passwort danach in der Oberfläche ändert, verliert die Änderung beim nächsten Neustart.

Was getestet wurde und was nicht

In der eigenen Testumgebung ausgeführt und bestätigt: Start mit dem Image gtstef/filebrowser:1.5.6-stable-slim, Logprüfung, Healthcheck auf /health, Login per API mit richtigem und falschem Passwort, Zugriffsschutz ohne Token, Anlegen einer Datei per API, Ändern des Admin-Passworts, Persistenz nach Neustart, das Verhalten von FILEBROWSER_ADMIN_PASSWORD bei Neustarts, Backup von Datenbank, Konfiguration und Nutzdaten sowie ein vollständiger Restore nach dem Löschen aller Daten. Zusätzlich wurden vier Fehlerbilder gezielt provoziert, deren Meldungen unten wörtlich stehen.

Nicht getestet, Angaben stammen aus der offiziellen Dokumentation: OIDC, LDAP, Proxy-Authentifizierung und 2FA, der Betrieb hinter einem Reverse Proxy mit TLS, Freigabelinks, WebDAV, das Vollimage mit FFmpeg und Office-Vorschau sowie das Upgrade auf die Beta-Reihe v2.0. Die Weboberfläche selbst wurde nicht im Browser bedient, alle Funktionstests liefen über dieselbe HTTP-API, die auch die Oberfläche nutzt.

Nutzen und Grenzen von FileBrowser Quantum

FileBrowser Quantum stellt vorhandene Verzeichnisse im Browser dar. Es gibt keine eigene Dateiablage und keinen Sync-Client: Was im gemounteten Ordner liegt, sieht die Oberfläche, und was über die Oberfläche hochgeladen wird, landet als normale Datei im Ordner. Das macht den Einstieg einfach und das Backup übersichtlich.

Laut README bietet das Projekt unter anderem:

mehrere Quellverzeichnisse (Sources) gleichzeitig mit Include- und Exclude-Regeln
Anmeldung per Passwort mit 2FA, OIDC, LDAP, JWT oder Proxy-Header
indizierte Echtzeitsuche inklusive Ordnergrößen
Vorschaubilder für Office-Dateien, Videos und 3D-Modelle (nur im Vollimage)
WebDAV-Zugriff und fein granulare Rechte pro Benutzer, Gruppe und Pfad
Freigabelinks mit Ablaufzeit, Passwort und Upload-Rechten
langlebige API-Tokens und eine Swagger-Seite unter /swagger

Grenzen: Es gibt keine Desktop-Synchronisation, keine Mobil-App, keine Kalender- oder Kontaktfunktionen und laut Vergleichstabelle im README weder S3- noch FTP-Anbindung, Kontingente oder Papierkorb (letztere als in Arbeit markiert). Die Shell-Befehlsfunktion des Originals wurde im Fork bewusst entfernt. Wer echte Zusammenarbeit mit Sync und Office braucht, ist mit Nextcloud besser bedient, wer SFTP und WebDAV für externe Partner anbieten will, mit SFTPGo.

Abgrenzung zum Original filebrowser/filebrowser

Das ursprüngliche Projekt filebrowser/filebrowser ist laut eigenem README seit dem 01.09.2026 archiviert: keine weiteren Releases, Bugfixes oder Sicherheitskorrekturen. Das letzte Release war v2.63.23 vom 27.07.2026, die GitHub-API meldete am 25.09.2026 den Status archived: true. Das README nennt zwei bekannte, nicht mehr behobene Problemklassen, nämlich die Befehlsausführung und das Session-Handling mit nicht widerrufbaren JWTs, und empfiehlt, den Dienst nicht direkt ins Internet zu stellen. Neuinstallationen sollten deshalb nicht mehr auf dem Original aufsetzen.

FileBrowser Quantum (gtsteffaniak/filebrowser) ist ein eigenständiger Fork mit anderer Konfiguration (YAML-Datei statt CLI-Flags), anderem Image (gtstef/filebrowser) und anderer Datenbank. Eine bestehende Installation des Originals lässt sich nicht einfach durch Tausch des Image-Namens umstellen. Die Doku hat dafür einen eigenen Migrationsbereich, der hier nicht getestet wurde.

Projektstand und getestete Version

Merkmal	Wert (abgerufen am 25.09.2026)
Repository	gtsteffaniak/filebrowser, Apache-2.0, nicht archiviert
GitHub	8.420 Stars, 446 Forks, letzter Push 25.09.2026
Letztes stabiles Release	v1.5.6-stable vom 04.09.2026
Beta-Reihe	v2.0.8-beta vom 21.09.2026
Getestetes Image	`gtstef/filebrowser:1.5.6-stable-slim`, Log meldet `v1.5.6-stable`

Das Release v1.5.6-stable behebt laut Release-Notes eine als moderat eingestufte Lücke (GHSA-55mw-cwg7-m8f5), bei der die öffentliche Metadaten-API anonymen Besuchern einer Freigabe Dateiinhalte lieferte und dabei Download-Limit und Viewer-Einstellung ignorierte. Wer Freigabelinks nutzt, sollte mindestens auf diesem Stand sein.

Stable oder Beta? Die Doku empfiehlt Neueinsteigern ausdrücklich die Reihe v1.5.x über den Tag stable. Die Beta v2.0 nutzt ein neues Datenbankformat (filebrowser.sqlite statt database.db), eine umgebaute Konfiguration und erfordert eine einmalige Migration. Diese Anleitung bezieht sich deshalb vollständig auf v1.5.x.

Voraussetzungen, Ressourcen und Architekturen

Linux-Host mit Docker Engine und Compose-Plugin v2
ein Verzeichnis mit den freizugebenden Dateien, niemals / oder /var (Hinweis der Doku)
für Zugriff von außen: Domain, Reverse Proxy und TLS-Zertifikat
RAM: Das README nennt 512 MB als Mindestanforderung. Im Test belegte der Slim-Container mit einem kleinen Testordner nur rund 39 MiB bei einem gesetzten Limit von 256 MB. Bei großen Verzeichnisbäumen wächst der Suchindex, dann ist deutlich mehr einzuplanen.
Cache-Verzeichnis: Das Programm warnte im Test, wenn weniger als 20 GB frei sind oder der Datenträger langsam schreibt. Der Cache sollte auf einer echten, schnellen Platte liegen.

Image-Tag	Inhalt	Architekturen (per `docker manifest inspect` geprüft)
`1.5.6-stable`, `stable`	mit FFmpeg und Dokumentvorschau	amd64, arm64
`1.5.6-stable-slim`, `stable-slim`	nur Kerndienst	amd64, arm64, arm (armv7)

Das getestete Slim-Image belegte lokal 87,1 MB. Für Tags empfiehlt die Doku im Produktivbetrieb die Minor-Variante wie 1.5-stable, die Patch-Updates mitnimmt, aber keinen Versionssprung auf v2 macht.

Verzeichnisstruktur, compose.yaml und config.yaml

Die Doku legt Konfiguration, Datenbank und Cache gemeinsam in ein Datenverzeichnis, das nach /home/filebrowser/data gemountet wird. Das Image setzt dafür selbst FILEBROWSER_CONFIG=/home/filebrowser/data/config.yaml und FILEBROWSER_DATABASE=/home/filebrowser/data/database.db.

# Projektverzeichnis anlegen
sudo mkdir -p /opt/filebrowser/data /srv/dateien
cd /opt/filebrowser
# Datenverzeichnis dem Container-Benutzer 1000:1000 übergeben
sudo chown -R 1000:1000 /opt/filebrowser/data /srv/dateien

Die compose.yaml entspricht der im Test verwendeten Datei, nur Pfade und Port sind für den Betrieb angepasst. Der Port ist an 127.0.0.1 gebunden, damit der Dienst nur über den Reverse Proxy erreichbar ist.

services:
  filebrowser:
    image: gtstef/filebrowser:1.5-stable-slim
    container_name: filebrowser
    user: "1000:1000"
    # Nur für den allerersten Start, danach entfernen (siehe Erstkonfiguration)
    environment:
      FILEBROWSER_ADMIN_PASSWORD: ${FB_ADMIN_PASSWORD:?FB_ADMIN_PASSWORD fehlt}
    volumes:
      - /srv/dateien:/folder
      - ./data:/home/filebrowser/data
    ports:
      - "127.0.0.1:8091:80"
    restart: unless-stopped
    mem_limit: 512m

Die Datei data/config.yaml:

server:
  cacheDir: /home/filebrowser/data/tmp
  database: /home/filebrowser/data/database.db
  sources:
    - path: /folder
      name: dateien
      config:
        defaultEnabled: true
auth:
  adminUsername: admin

Die Datei .env im selben Verzeichnis wie die compose.yaml, mit Rechten 600:

FB_ADMIN_PASSWORD=HIER-EIN-LANGES-ZUFALLSPASSWORT

Die wichtigsten Parameter:

user: "1000:1000": Das Image läuft ab v1.3 ohnehin als Benutzer filebrowser mit UID und GID 1000. Die explizite Angabe dokumentiert das und muss zu den Rechten der Bind-Mounts passen.
/srv/dateien:/folder: das freigegebene Verzeichnis. Der Pfad in sources.path ist immer aus Sicht des Containers anzugeben.
name: dateien: Name der Source, wird in API-Aufrufen als Parameter source benötigt.
defaultEnabled: true: neue Benutzer erhalten automatisch Zugriff auf diese Source.
cacheDir: Zwischenspeicher für Vorschauen und Uploads, im Datenverzeichnis persistent.
Ohne config.yaml startet der Container nicht, siehe Fehlerbilder. Laut Doku lautet der Standard-Login ohne eigene Vorgabe admin/admin, deshalb das Passwort schon beim Erststart setzen.

Installation und Start

# Stack starten
docker compose up -d
# Status prüfen, nach etwa 10 Sekunden sollte healthy erscheinen
docker compose ps
# Startmeldungen prüfen
docker compose logs --no-log-prefix | grep -E 'Initializing|Sources|Running'

Im Test lieferte das Log unter anderem:

[INFO ] Using admin password from FILEBROWSER_ADMIN_PASSWORD environment variable
[INFO ] Initializing FileBrowser Quantum (v1.5.6-stable)
[INFO ] Using Config file        : /home/filebrowser/data/config.yaml
[INFO ] Auth Methods             : [password]
[INFO ] Creating new database    : /home/filebrowser/data/database.db
[INFO ] Sources                  : [dateien: /folder]
[INFO ] Running at               : http://0.0.0.0/

Die Warnung database file could not be found beim allerersten Start ist normal, danach meldet das Log Using existing database.

Erstkonfiguration: Admin-Passwort richtig setzen

Im Test zeigte sich ein Verhalten, das in der Praxis leicht zum Sicherheitsproblem wird. Solange FILEBROWSER_ADMIN_PASSWORD gesetzt ist, schreibt FileBrowser Quantum bei jedem Start das Admin-Passwort neu. Das Log meldet dann Resetting admin user to default username and password.. Ein danach geändertes Passwort (im Test per API, also über denselben Endpunkt, den die Oberfläche nutzt) war nach docker compose restart ungültig, das Passwort aus der .env funktionierte wieder. Ohne die Variable blieb das geänderte Passwort über einen Neustart erhalten.

Der empfohlene Ablauf deshalb:

Erststart mit langem Zufallspasswort in der .env.
Als admin anmelden und unter Einstellungen das Passwort ändern, optional 2FA aktivieren.
Den Block environment aus der compose.yaml entfernen, die Zeile aus der .env löschen und mit docker compose up -d neu erstellen.
Im Log prüfen, dass Resetting admin user nicht mehr erscheint.

Alternativ kann die Variable dauerhaft bleiben, dann ist die .env die einzige Stelle, an der das Passwort gepflegt wird. Wichtig ist nur, sich bewusst für eines der beiden Modelle zu entscheiden.

Die Passwortänderung lässt sich auch per API erledigen, so wurde sie im Test ausgeführt. Das aktuelle Passwort muss URL-kodiert im Header X-Password stehen:

# Token holen
TOKEN=$(curl -s -X POST "http://127.0.0.1:8091/api/auth/login?username=admin" \
  -H "X-Password: AKTUELLES-PASSWORT")
# Passwort des Benutzers mit ID 1 (admin) ändern, Antwort HTTP 204
curl -s -o /dev/null -w '%{http_code}\n' -X PUT "http://127.0.0.1:8091/api/users?id=1" \
  -H "Authorization: Bearer $TOKEN" \
  -H "X-Password: AKTUELLES-PASSWORT" \
  -H "Content-Type: application/json" \
  -d '{"which":["password"],"data":{"password":"NEUES-PASSWORT"}}'

Funktionstest und Healthcheck

Das Image bringt einen eigenen Healthcheck mit: curl -f http://localhost:80/health alle 30 Sekunden, Timeout 3 Sekunden, Startphase 10 Sekunden, 3 Wiederholungen. Wer server.port in der config.yaml ändert, muss laut Doku den Healthcheck in der compose.yaml anpassen, sonst meldet Docker den Container als unhealthy.

# Healthcheck von außen, erwartet {"message":"ok"} und HTTP 200
curl -s -w ' HTTP %{http_code}\n' http://127.0.0.1:8091/health
# Datei per API anlegen
curl -s -X POST "http://127.0.0.1:8091/api/resources?source=dateien&path=%2Ftest%2Fhallo.txt" \
  -H "Authorization: Bearer $TOKEN" --data-binary 'Hallo'
# Datei mit Inhalt abfragen
curl -s -H "Authorization: Bearer $TOKEN" \
  "http://127.0.0.1:8091/api/resources?source=dateien&path=%2Ftest%2Fhallo.txt&content=true"

Im Test lieferte /health die Antwort {"message":"ok"} mit HTTP 200. Ein falsches Passwort beim Login ergab HTTP 401, ein Zugriff auf /api/resources ohne Token ebenfalls HTTP 401. Die per API angelegte Datei lag danach als normale Datei mit Eigentümer 1000:1000 im gemounteten Ordner und war nach einem Neustart weiterhin abrufbar.

Persistente Daten, Rechte und Bind-Mounts

data/database.db: Benutzer, Einstellungen, Freigaben, API-Tokens. Im Test mit Rechten 0600 angelegt.
data/config.yaml: die Konfiguration.
data/tmp: Cache, kann bei Backups ausgelassen werden.
Der Quellordner, hier /srv/dateien: die eigentlichen Nutzdaten.

Alle Verzeichnisse müssen für UID 1000 schreibbar sein. Wer eine andere UID nutzt, etwa 1001 auf manchen NAS-Systemen, setzt sie in user: und passt die Rechte mit chown -R 1001:1001 ./data an, wie es auch die Doku beschreibt. Rechte in FileBrowser selbst (Lesen, Schreiben, Löschen) wirken nur innerhalb der Oberfläche. Was das Dateisystem dem Container verbietet, kann auch ein FileBrowser-Admin nicht.

Ports unter 1024 im Container benötigen bei rootlosem Docker oder Podman die Capability NET_BIND_SERVICE. Mit dem gezeigten Mapping auf den internen Port 80 unter normalem Docker war das im Test nicht nötig.

Netzwerkfreigabe, Reverse Proxy und TLS

Dieser Abschnitt ist nur dokumentiert, nicht getestet. FileBrowser Quantum spricht selbst nur HTTP und gehört vor einen Reverse Proxy mit TLS. Laut Doku müssen die Header Host, X-Forwarded-For und X-Forwarded-Proto durchgereicht werden, weil das Session-Cookie an den Host gebunden ist. Für Echtzeit-Updates per Server-Sent Events sollte das Puffern abgeschaltet werden. Minimalbeispiel für nginx auf eigener Subdomain:

server {
    listen 443 ssl;
    server_name dateien.example.com;
    # ssl_certificate und ssl_certificate_key hier eintragen
    location / {
        proxy_pass http://127.0.0.1:8091;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        client_max_body_size 10G;
    }
}

Für Freigabelinks sollte in der config.yaml unter server der Eintrag externalUrl: "https://dateien.example.com" gesetzt werden, sonst erzeugt die Oberfläche Links mit interner Adresse. Bei einem Unterpfad kommt baseURL hinzu. Die Doku beschreibt außerdem, dass /public/ für Freigaben ohne vorgeschaltete Proxy-Authentifizierung erreichbar sein muss, während /api/, /dav/ und /swagger/ geschützt werden können. Wer Anmeldung per OIDC oder Proxy-Header nutzen will, findet die Optionen im Abschnitt Authentication der Doku.

Backup und Restore

Die Datenbank ist eine einzelne Datei. Das Log meldet SQL Journal Mode : OFF, ein Kopieren im laufenden Betrieb ist daher riskant. Im Test wurde der Container für das Backup kurz angehalten:

# Container anhalten, damit die Datenbank konsistent ist
cd /opt/filebrowser
docker compose stop
# Freien Platz am Ziel prüfen
df -h /backup
# Konfiguration, Datenbank und Nutzdaten sichern, Cache auslassen
sudo tar -czf /backup/filebrowser-$(date +%F).tar.gz --exclude=data/tmp data -C /srv dateien
# Wieder starten
docker compose start

Der Restore wurde gegen einen komplett gelöschten Zustand geprüft (im Test mit gleichwertigen tar-Befehlen und relativen Pfaden im Testverzeichnis): Container entfernt, Datenverzeichnis und Nutzdaten gelöscht, Archiv entpackt, neu gestartet. Die SHA-256-Prüfsummen von database.db und der Testdatei stimmten mit dem Original überein, die UID 1000 blieb erhalten. Danach meldete das Log Using existing database, der Healthcheck antwortete mit HTTP 200, das zuvor geänderte Admin-Passwort funktionierte und die Testdatei war mit identischem Inhalt abrufbar.

# Restore
cd /opt/filebrowser
docker compose down
sudo tar -xzf /backup/filebrowser-2026-09-25.tar.gz -C /opt/filebrowser data
sudo tar -xzf /backup/filebrowser-2026-09-25.tar.gz -C /srv dateien
sudo chown -R 1000:1000 /opt/filebrowser/data /srv/dateien
docker compose up -d

Für große Datenbestände ist ein inkrementelles Werkzeug wie restic oder Borg sinnvoller als ein Tar-Archiv. Die Datenbank sollte dabei trotzdem nur im gestoppten Zustand oder als vorher erstellte Kopie gesichert werden.

Updates und Rollback

# Vorher Backup wie oben erstellen, dann
docker compose pull
docker compose up -d
docker compose logs --no-log-prefix | grep Initializing

Mit dem Tag 1.5-stable-slim kommen nur Patch-Releases der Reihe 1.5. Die Tags stable und latest folgen laut Versionsseite der jeweils aktuellen stabilen Reihe und dürften damit auf v2 wechseln, sobald diese stabil wird. Für planbare Updates deshalb den Minor-Tag verwenden.
Ein Rollback auf ein älteres Patch-Release derselben Reihe ist durch Zurücksetzen des Tags möglich, sicher ist aber nur die Rückkehr zum Backup, weil die Datenbank beim Start verändert werden kann.
Der Sprung auf v2.0 ist laut Doku nicht umkehrbar ohne Backup: neues Datenbankformat, umgebaute Konfiguration (etwa trustProxyHeaders statt trustedHeaders), einmalige Migration. Vorher database.db sichern und die Migrationsanleitung durcharbeiten.

Typische Fehler mit Diagnose und Lösung

Die folgenden Meldungen wurden im Test gezielt provoziert und sind wörtlich übernommen.

Meldung	Ursache	Lösung
`[FATAL] config file /home/filebrowser/data/config.yaml does not exist`	Datenverzeichnis gemountet, aber ohne `config.yaml`	Datei anlegen oder `FILEBROWSER_CONFIG` setzen
`[FATAL] cacheDir failed to create cache directory: mkdir /home/filebrowser/data/tmp: permission denied`	Datenverzeichnis gehört root, Container läuft als 1000	`chown -R 1000:1000 data`
`Bind for 127.0.0.1:18092 failed: port is already allocated`	Hostport belegt	`ss -ltnp` prüfen, anderen Port wählen
`{"status":500,"message":"could not get index: gibtsnicht "}`	API-Aufruf mit falschem Source-Namen	Namen aus `sources.name` verwenden
`[WARN ] cacheDir only has 1.11 GB of free space`	Cache auf kleinem oder langsamem Datenträger	Cache auf schnelle Platte mit mindestens 20 GB frei legen

Geändertes Admin-Passwort gilt nach Neustart nicht mehr: FILEBROWSER_ADMIN_PASSWORD ist noch gesetzt, im Log steht Resetting admin user. Variable entfernen, siehe Erstkonfiguration.
Login funktioniert per IP, aber nicht über die Domain: Laut Doku fehlt meist der Host-Header im Reverse Proxy, das Cookie passt dann nicht zur Domain.
Container dauerhaft unhealthy: server.port geändert, Healthcheck prüft weiter Port 80. Healthcheck in der compose.yaml überschreiben.

Saubere Deinstallation

Achtung, Datenverlust: Die folgenden Befehle löschen Benutzer, Freigaben und Einstellungen unwiderruflich. Der Quellordner mit den Nutzdaten wird bewusst nicht gelöscht, weil er in der Regel unabhängig von FileBrowser weiter gebraucht wird. Vorher ein Backup ziehen und prüfen.

# Container und Netzwerk entfernen
cd /opt/filebrowser
docker compose down -v --remove-orphans
# Image entfernen
docker rmi gtstef/filebrowser:1.5-stable-slim
# Konfiguration und Datenbank löschen, NICHT /srv/dateien
sudo rm -rf /opt/filebrowser

Einen Reverse-Proxy-Eintrag und DNS-Eintrag für die Subdomain danach ebenfalls entfernen, sonst zeigt die Domain auf einen nicht mehr vorhandenen Dienst.

Passende Anleitungen auf S-EDV

SFTPGo als SFTP- und WebDAV-Server: die bessere Wahl, wenn Partner per SFTP oder WebDAV statt über den Browser zugreifen sollen.
copyparty als Dateiserver mit Docker: eine weitere schlanke Alternative für Up- und Downloads im Browser.
Nginx als Reverse Proxy mit TLS einrichten: die Grundlage, um FileBrowser Quantum verschlüsselt erreichbar zu machen.

Quellen

gtsteffaniak/filebrowser auf GitHub: README mit Funktionsumfang und Vergleichstabelle, Projektdaten abgerufen am 25.09.2026.
Release v1.5.6-stable: Release-Notes mit GHSA-55mw-cwg7-m8f5.
Offizielle Dokumentation FileBrowser Quantum: Docker-Anleitung v1.5.x, Konfigurationsdateien, Versionen und Reverse Proxy.
Quelltext der Dokumentation auf GitHub: Markdown-Fassung der Seiten docker-v1.5.x, config-v1.5.x, version und reverse-proxy-v1.5.x.
filebrowser/filebrowser auf GitHub: Archivierungshinweis vom 01.09.2026 und bekannte offene Sicherheitsthemen des Originals.
Image gtstef/filebrowser auf Docker Hub: verfügbare Tags.