FileBrowser Quantum mit Docker Compose: Dateien im Browser selbst verwalten

FileBrowser Quantum ist ein webbasierter Dateimanager für Server und NAS: ein Container, der Verzeichnisse mit Benutzerverwaltung, Suche, Vorschau und Freigabelinks bereitstellt. Es ist ein aktiver Fork des klassischen File Browser.

Beschrieben wird Version 2.0.1 mit Docker. Wichtigster Fund: FILEBROWSER_ADMIN_PASSWORD setzt das Admin-Passwort bei jedem Start zurück, ein geändertes Passwort geht verloren.

Nutzen und Grenzen von FileBrowser Quantum

Es zeigt vorhandene Verzeichnisse ohne eigene Ablage und Sync-Client, Uploads sind normale Dateien im Ordner.

Laut README 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: keine Desktop-Synchronisation, keine Mobil-App, keine Kalender- oder Kontaktfunktionen, laut README-Vergleichstabelle weder S3, FTP, Kontingente noch Papierkorb (letztere in Arbeit). Die Shell-Befehlsfunktion des Originals entfiel. Besser: Nextcloud für Sync und Office, SFTPGo für SFTP und WebDAV mit Partnern.

Abgrenzung zum Original filebrowser/filebrowser

Das Original filebrowser/filebrowser ist laut README seit dem 01.09.2026 archiviert, ohne Releases und Sicherheitskorrekturen (letztes Release v2.63.23 vom 27.07.2026). Offen sind laut README Befehlsausführung und nicht widerrufbare JWTs. Nutzen Sie es nicht für Neuinstallationen.

FileBrowser Quantum (gtsteffaniak/filebrowser) ist ein eigenständiger Fork mit YAML-Konfiguration statt CLI-Flags, anderem Image (gtstef/filebrowser) und anderer Datenbank. Ein Tausch des Image-Namens migriert nicht, die Doku hat einen Migrationsbereich.

Projektstand und getestete Version

v2.0.1-stable schließt laut Release-Notes eine hoch eingestufte Lücke (GHSA-c84q-q5g6-r47f): Konten mit „..“ im Namen konnten aus ihrem Verzeichnis ausbrechen.

Stable oder Beta? Stabil ist die Reihe 2.0 mit SQLite, Beta ist 2.1. Die Anleitung gilt für 2.0.x, der Umstieg von 1.5.x steht unter „Updates und Rollback“.

Voraussetzungen, Ressourcen und Architekturen

• Linux-Host (x86-64, ARM64, ARMv7) mit Docker und Compose v2, 1 CPU-Kern, 512 MB RAM
• 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. Der Slim-Container belegt rund 39 MiB, der Index wächst mit großen Bäumen.
• Cache-Verzeichnis: Das Log warnt bei unter 20 GB freiem Platz oder langsamem Datenträger.

Das Slim-Image belegte 93,3 MB. Zum Festschreiben nennt die Doku Tags wie 2.0-stable oder 2.0.1-stable.

Verzeichnisstruktur, compose.yaml und config.yaml

Konfiguration, Datenbank und Cache liegen in /home/filebrowser/data. Das Image setzt FILEBROWSER_CONFIG=/home/filebrowser/data/config.yaml und FILEBROWSER_DATABASE_PATH=/home/filebrowser/data/database.sqlite selbst; der Pfad in der config.yaml hat Vorrang.

# 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 zeigt den Aufbau, der Port ist an 127.0.0.1 gebunden (Zugriff über Reverse Proxy).

services:
  filebrowser:
    image: gtstef/filebrowser:2.0-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:
    path: /home/filebrowser/data/filebrowser.sqlite
  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 als Benutzer filebrowser (UID/GID 1000), passend zu den Bind-Mount-Rechten.
• /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.
• database.path: die SQLite-Datei (seit 2.0 ein Objekt).
• Ohne config.yaml startet der Container nicht. Ohne gesetztes Passwort erzeugt 2.0 laut Doku ein Zufallspasswort, schreibt es einmal ins Log und verlangt beim ersten Login einen Wechsel.

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'

Das Log liefert unter anderem:

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

Bei jedem weiteren Start meldet das Log Using existing database.

Erstkonfiguration: Admin-Passwort richtig setzen

Solange FILEBROWSER_ADMIN_PASSWORD gesetzt ist, schreibt FileBrowser Quantum bei jedem Start das Admin-Passwort neu (Log: Resetting admin user to default username and password.). Ein per API geändertes Passwort war nach docker compose restart ungültig.

Der empfohlene Ablauf deshalb:

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

Alternativ bleibt die Variable gesetzt, dann pflegen Sie das Passwort nur in der .env.

Per API steht das aktuelle Passwort URL-kodiert im Header X-Password:

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

Funktionstest und Healthcheck

Healthcheck im Image: curl -f http://localhost:80/health alle 30 s, Timeout 3 s, Startphase 10 s, 3 Wiederholungen. Bei geändertem http.port passen Sie ihn in der compose.yaml an, sonst meldet Docker unhealthy. Weitere Härtung mit Healthchecks, Secrets und Non-Root beschreibt Docker Compose absichern.

# 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"

Ein Aufruf von /health liefert {"message":"ok"} mit HTTP 200. Ein falsches Passwort und /api/resources ohne Token liefern jeweils HTTP 401. Die per API angelegte Datei gehört 1000:1000 und bleibt nach einem Neustart abrufbar.

Persistente Daten, Rechte und Bind-Mounts

• data/filebrowser.sqlite samt -wal und -shm: Benutzer, Einstellungen, Freigaben, API-Tokens.
• 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. Bei anderer UID (etwa 1001 auf manchen NAS) setzen Sie sie in user: und führen chown -R 1001:1001 ./data aus. Was das Dateisystem verbietet, kann auch ein FileBrowser-Admin nicht.

Ports unter 1024 brauchen bei rootlosem Docker oder Podman die Capability NET_BIND_SERVICE.

Netzwerkfreigabe, Reverse Proxy und TLS

FileBrowser Quantum spricht nur HTTP, nutzen Sie einen Reverse Proxy mit TLS. Reichen Sie Host, X-Forwarded-For und X-Forwarded-Proto durch (Cookie am Host gebunden) und schalten Sie Puffern aus. 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 setzen Sie in der config.yaml unter http trustProxyHeaders: true (sonst sieht FileBrowser nur die Proxy-Adresse) und externalUrl: "https://dateien.example.com", sonst enthalten Links die interne Adresse; bei Unterpfad zusätzlich baseURL. /public/ muss ohne vorgeschaltete Proxy-Authentifizierung erreichbar sein, /api/, /dav/ und /swagger/ lassen sich schützen. OIDC und Proxy-Header: siehe Doku, Abschnitt Authentication.

Backup und Restore

Das Log meldet SQL Journal Mode : OFF, Kopieren im Betrieb ist riskant. Halten Sie den Container für das Backup kurz an:

# 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

Nach dem Entpacken des Archivs und einem Neustart sind Datenbank, Anmeldung und Dateien wieder da.

# 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 Bestände eignen sich restic oder Borg, die Datenbank nur gestoppt oder als Kopie sichern.

Updates und Rollback

# Vorher Backup wie oben erstellen, dann

$ docker compose pull
$ docker compose up -d
$ docker compose logs --no-log-prefix | grep Initializing

• 2.0-stable-slim bringt nur Patch-Releases der Reihe 2.0, stable und latest folgen der jeweils neuesten stabilen Reihe. Nutzen Sie den Minor-Tag.
• Rollback auf ein älteres Patch-Release geht per Tag, sicher ist nur das Backup, weil der Start die Datenbank verändern kann.

Umstieg von 1.5.x auf 2.0

2.0 ersetzt die BoltDB-Datei durch SQLite. Ein reiner Tag-Wechsel scheitert an der alten config.yaml. So gehen Sie vor:

$ cd /opt/filebrowser
$ docker compose stop
$ sudo cp -a data/database.db /backup/database.db.backup
$ sudo mv data/database.db data/database.db.old

In der config.yaml wird database zu:

  database:
    path: /home/filebrowser/data/filebrowser.sqlite
    migrateFrom: /home/filebrowser/data/database.db.old

Dann Tag auf 2.0-stable-slim ändern und starten. Das Log meldet Migration completed successfully!; Benutzer, Passwörter und Freigaben blieben erhalten. Danach migrateFrom entfernen und neu starten.

Skripte: PUT /api/users liefert 405 (jetzt PATCH), /api/raw entfällt, HTTP-Optionen stehen unter http.

Typische Fehler mit Diagnose und Lösung

Typische Meldungen:

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

http.port geändert, Healthcheck prüft weiter Port 80. Healthcheck in der compose.yaml überschreiben.

Saubere Deinstallation

Achtung, Datenverlust: Die Befehle löschen Benutzer, Freigaben und Einstellungen unwiderruflich, der Quellordner bleibt. Sichern Sie vorher.

# Container und Netzwerk entfernen

$ cd /opt/filebrowser
$ docker compose down -v --remove-orphans

# Image entfernen

$ docker rmi gtstef/filebrowser:2.0-stable-slim

# Konfiguration und Datenbank löschen, NICHT /srv/dateien

$ sudo rm -rf /opt/filebrowser

Entfernen Sie danach Reverse-Proxy- und DNS-Eintrag.

Passende Anleitungen auf S-EDV

• SFTPGo als SFTP- und WebDAV-Server
• copyparty als Dateiserver mit Docker
• Nginx als Reverse Proxy mit TLS einrichten

Quellen

• gtsteffaniak/filebrowser auf GitHub
• Release v2.0.0-stable und v2.0.1-stable
• Migrationsanleitung 1.x auf 2.0
• Offizielle Dokumentation FileBrowser Quantum
• Quelltext der Dokumentation auf GitHub
• filebrowser/filebrowser auf GitHub
• Image gtstef/filebrowser auf Docker Hub