--- title: "FileBrowser Quantum mit Docker Compose: Dateien im Browser selbst verwalten" date: 2026-09-25T02:22:50+02:00 modified: 2026-11-08T15:13:25+01:00 category: docker type: how_to author: Marcel Schönfelder canonical: https://s-edv.com/anleitungen/filebrowser-quantum-docker-compose-dateimanager-selfhosting keywords: - FileBrowser Quantum - Dateimanager - Docker Compose - Selfhosting - WebDAV - Backup reading_time: 10 personalize_url: "https://s-edv.com/anleitungen/filebrowser-quantum-docker-compose-dateimanager-selfhosting#domain={domain}" variables: - name: fb_admin_password label: "Fb admin password" default: "HIER-EIN-LANGES-ZUFALLSPASSWORT" - name: domain label: "Ihre Domain" default: "example.com" --- # FileBrowser Quantum mit Docker Compose: Dateien im Browser selbst verwalten ## Anpassbare Werte Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`: | Platzhalter | Bedeutung | Beispielwert | | --- | --- | --- | | `{{fb_admin_password}}` | Fb admin password | `HIER-EIN-LANGES-ZUFALLSPASSWORT` | | `{{domain}}` | Ihre Domain | `example.com` | Link mit eigenen Werten: https://s-edv.com/anleitungen/filebrowser-quantum-docker-compose-dateimanager-selfhosting#domain=cloud.example.com Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. *Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben. 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. **Kurzfassung:** Legen Sie `/opt/filebrowser` mit `compose.yaml` (Image `gtstef/filebrowser:2.0-stable-slim`, Port nur auf `127.0.0.1:8091`), `data/config.yaml` und `.env` an, übergeben Sie Daten- und Quellverzeichnis an UID 1000 und starten Sie mit `docker compose up -d`. `FILEBROWSER_ADMIN_PASSWORD` setzt das Admin-Passwort bei jedem Start zurück: Ändern Sie das Passwort nach der ersten Anmeldung und entfernen Sie die Variable danach. `/health` muss HTTP 200 liefern. Von außen nur über einen Reverse Proxy mit TLS. Für Backups stoppen Sie den Container und sichern `data` und den Quellordner. ## 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 | Merkmal | Wert | | --- | --- | | Repository | gtsteffaniak/filebrowser, Apache-2.0, nicht archiviert | | Letztes stabiles Release | v2.0.1-stable vom 13.10.2026 | | Beta-Reihe | v2.1.2-beta vom 13.10.2026 | | Image in dieser Anleitung | `gtstef/filebrowser:2.0.1-stable-slim`, Log meldet `v2.0.1-stable` | 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. | Image-Tag | Inhalt | Architekturen (per `docker manifest inspect` geprüft) | | --- | --- | --- | | `2.0.1-stable`, `stable` | mit FFmpeg und Dokumentvorschau | amd64, arm64 | | `2.0.1-stable-slim`, `stable-slim` | nur Kerndienst | amd64, arm64, arm (armv7) | 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. ```bash # Projektverzeichnis anlegen ``` ```bash $ sudo mkdir -p /opt/filebrowser/data /srv/dateien $ cd /opt/filebrowser ``` ```bash # Datenverzeichnis dem Container-Benutzer 1000:1000 übergeben ``` ```bash $ 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). ```yaml 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`: Datei: `data/config.yaml` ```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: Datei: `compose.yaml` ```yaml FB_ADMIN_PASSWORD={{fb_admin_password}} ``` **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. > **Prüfen:** `ls -ln /opt/filebrowser/data /srv/dateien` zeigt Besitzer `1000 1000`, `docker compose config` läuft ohne Fehler durch. ## Installation und Start ```bash # Stack starten ``` ```bash $ docker compose up -d ``` ```bash # Status prüfen, nach etwa 10 Sekunden sollte healthy erscheinen ``` ```bash $ docker compose ps ``` ```bash # Startmeldungen prüfen ``` ```bash $ docker compose logs --no-log-prefix | grep -E 'Initializing|Sources|Running' ``` Das Log liefert unter anderem: ```bash [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`. > **Prüfen:** `docker compose ps` zeigt `(healthy)`, das Log enthält `Initializing FileBrowser Quantum (v2.0.1-stable)` und `Sources : [dateien: /folder]`. ## 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`: ```bash # 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"}}' ``` > **Prüfen:** Nach `docker compose restart` gelingt die Anmeldung mit dem neuen Passwort, und `docker compose logs | grep 'Resetting admin'` liefert nichts mehr. ## 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](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root). ```bash # 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. > **Prüfen:** `/health` antwortet mit `{"message":"ok"}` und HTTP 200, `ls -ln /srv/dateien/test` zeigt `hallo.txt` mit Besitzer 1000. ## 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`. > **Prüfen:** `docker compose exec filebrowser id` meldet `uid=1000`, und ein Upload über die Oberfläche erscheint als Datei im Quellordner. ## 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: ```nginx server { listen 443 ssl; server_name dateien.{{domain}}; # 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.{{domain}}"`, 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. > **Prüfen:** `curl -s https://dateien.{{domain}}/health` liefert `{"message":"ok"}`, die Anmeldung über die Domain gelingt, und ein Freigabelink beginnt mit der externen Adresse. ## 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: ```bash # Container anhalten, damit die Datenbank konsistent ist ``` ```bash $ cd /opt/filebrowser $ docker compose stop ``` ```bash # Freien Platz am Ziel prüfen ``` ```bash $ df -h /backup ``` ```bash # Konfiguration, Datenbank und Nutzdaten sichern, Cache auslassen ``` ```bash $ sudo tar -czf /backup/filebrowser-$(date +%F).tar.gz --exclude=data/tmp data -C /srv dateien ``` ```bash # Wieder starten ``` ```bash $ docker compose start ``` Nach dem Entpacken des Archivs und einem Neustart sind Datenbank, Anmeldung und Dateien wieder da. ```bash # Restore ``` ```bash $ 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. > **Prüfen:** `tar tzf /backup/filebrowser-*.tar.gz | grep filebrowser.sqlite` findet die Datenbank, nach dem Restore meldet das Log `Using existing database` und `/health` HTTP 200. ## Updates und Rollback ```bash # Vorher Backup wie oben erstellen, dann ``` ```bash $ 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: ```bash $ 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: ```yaml 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`. > **Prüfen:** Das Log zeigt die neue Version nach `Initializing`, `docker compose ps` meldet `(healthy)`, die Anmeldung funktioniert. ## Typische Fehler mit Diagnose und Lösung Typische Meldungen: | Meldung | Ursache | Lösung | | --- | --- | --- | | `[FATAL] old database path is set in the config, please migrate your database to SQLite` | 2.0 mit `config.yaml` aus 1.5 | `database.path` und `migrateFrom` setzen, siehe Umstieg | | `[FATAL] FILEBROWSER_DATABASE environment variable is deprecated` | Variable aus 1.5 | entfernen | | `[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** `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. ```bash # Container und Netzwerk entfernen ``` ```bash $ cd /opt/filebrowser $ docker compose down -v --remove-orphans ``` ```bash # Image entfernen ``` ```bash $ docker rmi gtstef/filebrowser:2.0-stable-slim ``` ```bash # Konfiguration und Datenbank löschen, NICHT /srv/dateien ``` ```bash $ sudo rm -rf /opt/filebrowser ``` Entfernen Sie danach Reverse-Proxy- und DNS-Eintrag. ## Passende Anleitungen auf S-EDV - [SFTPGo als SFTP- und WebDAV-Server](https://s-edv.com/anleitungen/sftpgo-synology-sftp-webdav-server) - [copyparty als Dateiserver mit Docker](https://s-edv.com/anleitungen/copyparty-docker-dateiserver-webdav-selfhosting) - [Nginx als Reverse Proxy mit TLS einrichten](https://s-edv.com/anleitungen/nginx-reverse-proxy-tls-einrichten) ## Quellen - [gtsteffaniak/filebrowser auf GitHub](https://github.com/gtsteffaniak/filebrowser) - [Release v2.0.0-stable](https://github.com/gtsteffaniak/filebrowser/releases/tag/v2.0.0-stable) und [v2.0.1-stable](https://github.com/gtsteffaniak/filebrowser/releases/tag/v2.0.1-stable) - [Migrationsanleitung 1.x auf 2.0](https://filebrowserquantum.com/en/docs/getting-started/v2/migration/) - [Offizielle Dokumentation FileBrowser Quantum](https://filebrowserquantum.com/en/docs/getting-started/) - [Quelltext der Dokumentation auf GitHub](https://github.com/quantumx-apps/filebrowserDocs) - [filebrowser/filebrowser auf GitHub](https://github.com/filebrowser/filebrowser) - [Image gtstef/filebrowser auf Docker Hub](https://hub.docker.com/r/gtstef/filebrowser)