How to move File Browser go FileBrowser Quantum
File Browser don archive and e no go get security fix again. Hide am from internet, back up filebrowser.db, write config.yaml, then run Quantum 1.5.8.
Why you suppose move File Browser go FileBrowser Quantum now
If you dey run File Browser for your VPS, your next job na to move am go FileBrowser Quantum. Upstream archive File Browser on 2026-08-31. Their own notice talk am clear: "There will be no further releases, bug fixes, or security fixes." Quantum na fork of File Browser wey still dey get updates. Quantum docs say you fit point am to your old database, so you no go need create all your users again.
Plenty people set File Browser up from one tutorial years ago. Maybe na office share for small business where staff dey drop invoice and scanned receipt. Maybe na family folder where everybody dey upload photo from phone. Whichever one, the app fit write to your disk, and anybody wey reach am over HTTP fit try am. Any new bug wey person find for am from now go stay open forever, because nobody go fix am.
We go do the work in four steps. First, comot the old app from public internet. Then back up wetin you get. After that, rebuild your config as config.yaml. Last, check some things by hand after Quantum start, because the docs no talk about them at all.
Step 1: Comot the old File Browser from public internet first
Before you start the migration, make sure say nobody fit reach the old app from internet. The migration fit take one evening or one week, and the old app no suppose dey public that whole time.
Check wetin dey listen. Most tutorial compose files publish port 8080 or 80 on every address.
sudo ss -tlnp | grep -E ':(80|8080)\b'If you see 0.0.0.0:8080 or [::]:8080, anybody for internet fit reach the app. Note this one well: ufw no dey protect you here. Docker write im own iptables rules for published ports, so port wey you publish as 0.0.0.0 dey reachable even when ufw status show am as closed. You fit see those rules with sudo iptables -L DOCKER -n.
Open the old compose file and bind the port to localhost only:
ports:
- "127.0.0.1:8080:80"Then recreate the container:
docker compose up -d
sudo ss -tlnp | grep 8080Now the line suppose show 127.0.0.1:8080. From your laptop, curl -m 5 http://YOUR_VPS_IP:8080 suppose fail to connect. Your reverse proxy (Caddy or nginx) wey dey forward to 127.0.0.1:8080 go still work, so people wey dey use the HTTPS address no go see any change. If you keep that public HTTPS address, the archive notice say the proxy must terminate TLS and do im own authentication. If your reverse proxy itself dey run inside Docker on the same network, remove the ports: block completely, because the proxy dey reach the app by service name and no need any published port.
If your Docker Engine old pass 28.0.0, machines for the same local network segment still fit reach ports wey you bind to localhost. Upgrade Docker before you rely on that bind for isolation.
If na only you and your family dey use am, e better make you comot am from public internet completely and reach am over Tailscale. sudo tailscale serve --bg http://127.0.0.1:8080 go make am available only inside your tailnet. To understand the difference between private access and public access, read Tailscale Serve versus Funnel and which one expose your app to the public. For this job you want Serve, no be Funnel.
While you still dey the old app, make sure the command runner dey off. The archive notice itself recommend am.
Step 2: Stop the old instance and back up everything
You no fit reverse this move. Quantum fit write to the database wey you give am, and nobody promise say the old File Browser go fit read am again. So your backup na your only way back.
First, find where your files really dey on the host. Different tutorials use different paths, so no guess:
docker inspect filebrowser | grep -E '"(Source|Destination)"'Change filebrowser to your container name if e different (docker ps go show am). Find the database file first. E dey usually called filebrowser.db or database.db. Next find the config file, wey dey usually called settings.json or .filebrowser.json. Then find the folder wey dey mounted at /srv, because na there your real files dey.
If you install the binary without Docker, the docs suggest make you check the flags wey the process start with:
ps aux | grep filebrowserLook for --port, --address, --baseurl, --database and --root. Write them down. You go need them for Step 4.
Now stop the old app. You must do this step. If the old process still hold the database open when Quantum start, the Quantum troubleshooting page say you go see "Database locked", and the fix na to stop the original instance.
docker compose stop
docker ps | grep filebrowserThe second command suppose print nothing. For binary install, use sudo systemctl stop filebrowser and confirm with systemctl is-active filebrowser. E suppose print inactive.
Then copy the database and config to one folder wey get the date for im name, and pack am:
mkdir -p ~/fb-backup-2026-10-02
sudo cp -a /path/to/filebrowser.db /path/to/settings.json ./docker-compose.yml ~/fb-backup-2026-10-02/
sudo tar czf ~/fb-backup-2026-10-02.tgz -C ~ fb-backup-2026-10-02
sudo chmod 600 ~/fb-backup-2026-10-02.tgzCopy the .tgz go another machine, outside the VPS. If the backup dey only on the same disk and that disk spoil, you go lose the backup too. For the full steps to stop, archive and restore a stack, read how to back up and upgrade a Docker Compose stack.
Step 3: Which Quantum tag you go pin
As of 4 November 2026, Quantum get two stable lines. The 2.x line no be beta again: 2.0.0-stable come out on 9 October 2026, and the README now talk say "v2.0.0 is now stable!" The current GitHub "Latest" release na 2.0.2-stable, released 23 October 2026. The 1.x line still dey get maintenance releases. Im newest tag na 1.5.8-stable, released 4 October 2026 with one high-severity security fix for TOTP login. The newest 2.x beta na 2.1.4-beta, released 31 October 2026. The docs version page recommend v2.0.x for new installs and keep 1.5-stable for legacy installs wey never ready to migrate.
This guide dey use the 1.5.x line. The config keys, the database path and the compose file wey dey below na for 1.5.x, and the Quantum v1 to v2 upgrade guide na for people wey dey already run Quantum 1.x. For office or family share wey people depend on, pin gtstef/filebrowser:1.5.8-stable. Never use :latest. With :latest, one docker compose pull fit carry you enter new major version wey change your config format and your permission model, even if you no decide am. This one no be story again: as of 4 November 2026, stable and latest dey point to 2.0.2-stable. With a pinned tag, upgrade only happen when you edit the file.
Note this one: the Quantum docs website dey describe 2.x. Some config keys for 1.5.x no be the same as wetin the docs show. Where e different, I go give you both names.
Step 4: Rebuild your config.json as config.yaml
Quantum no dey read the old JSON config. You go do am by hand. E no too long. The old config file fit carry plenty keys (cert, key, socket, tokenExpirationTime, disableExec and more), but the Quantum migration docs map only six of them, and na those six we go carry go the new file.
The Quantum docs give this mapping from each old flag to im new key. If your old container start with settings.json as im config file, the same names dey inside am. But settings.json wey you export from the app with filebrowser config export different: e no carry database key at all, so take the database path from the --database flag or from docker inspect.
--portor"port"goserver.porton 1.5.x (the 2.x docs write am ashttp.port)--addressor"address"goserver.listenon 1.5.x (the 2.x docs write am ashttp.listen). No beserver.address: the docs talk am straight, "The address key isserver.listen, notserver.address."--baseurlor"baseURL"goserver.baseURLon 1.5.x (the 2.x docs write am ashttp.baseURL)--databaseor"database"goserver.databaseon 1.5.x (the 2.x docs write am asserver.database.path)--rootor"root"goserver.sources[0].path- The output path from
--logor"log"goserver.logging[0].output.server.loggingna list of logging configurations; setlevels: "info|warning|error"for that entry.
Make the new folder and copy the database inside am. Copy am, no move am, so the original file go remain inside your backup folder as e be:
mkdir -p ~/quantum/data
sudo cp -a /path/to/filebrowser.db ~/quantum/data/filebrowser.db
sudo chown -R 1000:1000 ~/quantum/dataThe Quantum image dey run as user filebrowser, wey get UID and GID 1000. That user must own the data folder. If e no own am, the container go fail with "Permission denied". To understand why the user inside the container must match the folder owner on the host, read PUID and PGID in Docker explained.
Now write ~/quantum/data/config.yaml for 1.5.8-stable:
server:
port: 80
baseURL: "/"
database: "/home/filebrowser/data/filebrowser.db"
sources:
- name: "files"
path: "/srv"
auth:
methods:
password:
enabled: trueport: 80 na the port inside the container. You set the outside port for the compose file. If your old setup serve the app under one subpath like /files, put that same value for baseURL, or your reverse proxy go return 404.
The password block na auth.methods.password, and na the same key for 1.5.x and 2.x. You fit see passwordAuth inside the 1.5.x source code, but na method name wey the code dey use inside, no be YAML key. If you write auth.methods.passwordAuth or server.address for 2.x, the app no go start, because 2.x reject unknown keys at startup.
Step 5: The compose file for Quantum
Create ~/quantum/docker-compose.yml:
services:
filebrowser:
image: gtstef/filebrowser:1.5.8-stable
container_name: filebrowser-quantum
environment:
FILEBROWSER_CONFIG: /home/filebrowser/data/config.yaml
FILEBROWSER_DATABASE: /home/filebrowser/data/filebrowser.db
volumes:
- /srv/files:/srv
- ./data:/home/filebrowser/data
ports:
- "127.0.0.1:8080:80"
restart: unless-stoppedChange /srv/files to the same host folder wey the old container mount at /srv. I put the database path for both the environment and config.yaml on purpose. The 1.5.8 image set FILEBROWSER_DATABASE to /home/filebrowser/data/database.db by default. When the two places get the same path, Quantum no go use that default by mistake. On 2.x the variable name change to FILEBROWSER_DATABASE_PATH for the new SQLite file. 2.x refuse to start if FILEBROWSER_DATABASE still dey set, unless you set server.database.migrateFrom: "default" for config. With that setting, migration read the legacy database path from FILEBROWSER_DATABASE; after migration, rename the variable and point am to the new SQLite file. The ./data line na bind mount. E mean say the database dey as normal file for the host, wey you fit see and back up. To see why that one matter here, and when named volume go better, read bind mounts versus named volumes in Docker Compose.
Start am and watch the log:
cd ~/quantum
docker compose up -d
docker compose logs -f filebrowserWhen new lines stop to dey show, press Ctrl+C. Then check health:
curl -fsS http://127.0.0.1:8080/health && echo ok
docker compose psYou suppose see ok. After about 30 seconds, docker compose ps suppose show the container as healthy. If the log show "Fatal error creating tmp directory", the docs say make you set server.cacheDir for config.yaml to one path inside /home/filebrowser/data, and make sure UID 1000 own am.
Wetin no go follow you come Quantum
Quantum no get some old features at all, and the docs talk am straight:
- The Terminal don comot. Docs say na for security.
- Runners (the commands wey dey run when person upload or delete file) don comot. Docs say new job system go replace am later.
- The old
filebrowser userscommands don comot. You fit manage users through the web UI, config file, API or Quantum own CLI.
Quantum still get small CLI of im own. The users docs show filebrowser user set and filebrowser user promote on 2.x, and the troubleshooting page say you fit reset password through CLI. But the old filebrowser users commands no dey.
If you get scripts, the last one na the one wey go cause wahala for you. If you dey create staff accounts with filebrowser users add inside one shell script, that script go stop to work. Move am to the API before you shut down the old server for good.
Wetin you must check yourself after migration
The Quantum docs we read no talk whether these four things survive the move. We no go guess for you. Run each check and write down the result. If something break, open issue for the Quantum GitHub and talk exactly wetin you see.
- Password login. Log in with one normal user account wey you never touch for months, no be only the admin. If the password fail, the troubleshooting page say make you confirm say the database migration complete and the file permissions correct. E also say you fit reset password through the CLI.
- Scope paths. Log in as one user wey get access to only one folder, like staff wey see only
/srv/invoices. Confirm say that user still see the same folder as before, and no fit see any folder above am. This one na security check, no be just how the page look. - Share links. Open one old share link inside private browser window. Write down whether e still open the file, show error, or ask for password.
- Branding. Check whether your custom name and logo still show for the login page. On Quantum, the name dey for
frontend.nameinsideconfig.yaml.
Keep the old backup until all four checks pass and your users don use the new app for at least one week.
When 2.x turn stable: the permissions go move
Quantum 2.0.0-stable come out on 9 October 2026. From v2.0.0, file permissions (download, modify, create, delete) no dey for user level again; dem dey inside per-source scope, with one new view permission. Only admin, api, share and realtime remain as global permissions. The troubleshooting page say the upgrade go copy each user im old global permissions into each of im scopes automatically.
No just trust am. Check am. After you upgrade, open User Management and look at every user wey get more than one source. The docs list wetin you go see if something go wrong: WebDAV go show empty folders, or user go fit browse but no fit upload or delete. For API scripts wey dey create users, the docs say "new integrations should use scopes[].permissions". If your script no send permissions for one scope, the server go apply the Access management default permissions for that source, and any value wey you send go override the default. 2.x also change the database from BoltDB to SQLite, and e go import your old data on first start through migrateFrom. The docs get separate process for v1 to v2 upgrade, with one config migration tool. When time reach, follow that guide and pin the exact 2.x tag again.
If after all this you dey wonder whether Quantum na the right replacement for you, our comparison of self-hosted file managers compare am with the other options.
FAQ
Why Quantum dey show "Database locked" when e start?
The old File Browser still dey hold the database file open. The Quantum troubleshooting page list "Database locked" with one fix: stop the original instance. Run docker compose stop for the old stack, confirm with docker ps say e no dey run again, then start Quantum.
I fit just continue to run the archived v2.63.23 image?
File Browser no go get any security fix again; GitHub archive the repository on 2026-08-31. Any bug wey person find from now go stay open. If you must keep am small time, bind am to 127.0.0.1 or reach am only over Tailscale, and keep the command runner off.
Quantum go convert my config.json automatically?
No. Nothing go convert the old JSON config for you, so you go rewrite am as config.yaml by hand. The old file fit carry many keys, but the Quantum migration docs map six of them: port, address, baseURL, database, root and log. Each of those six get im own key for the new file (address go server.listen, no be server.address), and the database path must point to your copied filebrowser.db.
My script wey dey create users no work again. Why?
Quantum don remove the old filebrowser users commands. You fit manage users through the web UI, config file, API or Quantum own CLI. Quantum get small CLI wey fit create user or reset password, but e no use the old filebrowser users commands. On 2.x, the docs say new API integrations should put per-source permissions inside scopes[].permissions. If you leave them out for one scope, the server go apply the Access management default permissions for that source.
Which Quantum tag I suppose use?
As of 4 November 2026, Quantum get two stable lines: 2.0.2-stable, released 23 October 2026, and 1.5.8-stable on the 1.x line. This guide use gtstef/filebrowser:1.5.8-stable, because the config and compose file for here na for 1.5.x, and the docs still keep that line for legacy installs wey never ready to migrate. Pin the exact tag inside your compose file and never use :latest, so major upgrade go happen only when you choose am.