How to move File Browser go FileBrowser Quantum

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-09-01. 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.

The last image still dey pull, and na why many people never notice say the project don die. docker pull filebrowser/filebrowser:v2.63.23 still work today, the container still start, and the login page still show. Nothing for the app tell you say the software don stop to get fixes. Na exactly why many servers go still dey run am unpatched one year from now.

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 8080

Now the line suppose show 127.0.0.1:8080. From your laptop, curl -m 5 http://YOUR_VPS_IP:8080 suppose time out. 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 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 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 filebrowser

Look 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 filebrowser

The 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.tgz

Copy 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 2 October 2026, Quantum get two release lines. The newest stable tag na 1.5.6-stable, released 4 September 2026. The 2.x line still dey beta. The README talk say "v2.0.0 is now in beta", and the newest 2.x tag na 2.1.0-beta, released 30 September 2026.

For office or family share wey people depend on, pin gtstef/filebrowser:1.5.6-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. 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.6 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. One DietPi forum thread about this same migration observe say "there seems to be no automatic import/conversion method of the JSON", so you go do am by hand. E no too long, because the old file get only few keys.

The Quantum docs give this mapping from each old flag to im new key. The same names dey inside the old settings.json:

• --port or "port" go server.port
• --address or "address" go server.address
• --baseurl or "baseURL" go server.baseURL
• --database or "database" go server.database on 1.5.6 (the 2.x docs write am as server.database.path)
• --root or "root" go server.sources[0].path
• --log or "log" go server.logging

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/data

The 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.6-stable:

server:
  port: 80
  baseURL: "/"
  database: "/home/filebrowser/data/filebrowser.db"
  sources:
    - name: "files"
      path: "/srv"
auth:
  methods:
    password:
      enabled: true

port: 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.

On 1.5.6 the password block na auth.methods.password. The 2.x docs write am as auth.methods.passwordAuth. If you dey follow the docs website while you dey run 1.5.6, na this key go confuse you.

Step 5: The compose file for Quantum

Create ~/quantum/docker-compose.yml:

services:
  filebrowser:
    image: gtstef/filebrowser:1.5.6-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-stopped

Change /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.6 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. 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 filebrowser

When 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 ps

You 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.
• Command-line user management don comot. You go manage users through the config file or the API now.

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.

1. 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.
2. 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.
3. 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.
4. Branding. Check whether your custom name and logo still show for the login page. On Quantum, the name dey for frontend.name inside config.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

From v2.0.0, file permissions (view, download, modify, create, delete) no go dey for user level again. Each one go dey inside per-source scope. Only admin, api, share and realtime go 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. Any API script wey dey create users must change to scopes[].permissions. 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?

The image still pull and still run, but File Browser no go get any security fix again since 2026-09-01. 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 get only few keys: port, address, baseURL, database, root and log. Each one get im own key for the new file, and the database path must point to your copied filebrowser.db.

My script wey dey create users no work again. Why?

Quantum don remove command-line user management. You go manage users through the config file or the API now. On 2.x, API calls wey create users must also put permissions inside scopes[].permissions. The old top-level permissions only serve as defaults for new scopes.

Which Quantum tag I suppose use?

As of 2 October 2026, the newest stable tag na gtstef/filebrowser:1.5.6-stable, and 2.x still dey beta. Pin the exact tag inside your compose file and never use :latest, so major upgrade go happen only when you choose am.