What it is
FileBrowser is a web-based file manager running on my LAN host (Docker container name filebrowser, image filebrowser/filebrowser:s6). It brings shared directories on the NAS and various machines into a single browser page for management: upload, download, rename, create directories — no need to install a client on each machine.
Why
Files at home were scattered: one copy on the NAS, one on each machine, invisible to each other across screens. I wanted a unified entry point where I could open a browser and move in and out of directories, with permissions separated by account. Along the way, I also wanted to practice file permissions, reverse proxying, and directory sharing in a real environment.
Pitfalls
After deployment, login kept failing. Investigation showed it wasn't a password issue: the baseURL inside the container was empty, so the frontend sent login requests to the root path /api/login, while the root path /api/ had long been allocated to the quantitative research service. As a result, requests landed elsewhere, and login always failed.
The fix had three steps: use the official CLI to set baseURL to /files (requires brief downtime, since the database must be exclusive); add /files/api/ forwarding in Nginx Proxy Manager, strip the prefix, and point it back to FileBrowser's own /api/...; finally verify that the login endpoint is reachable and the quantitative endpoints are unaffected.
Current status
The container is Up 12 days (healthy) and in daily use. The configuration and fix scripts are kept in the repository; when switching machines or reinstalling, just follow them step by step.
Features
- 用 Docker 跑 FileBrowser，统一入口管理 NAS 与各机器共享目录
- 子路径部署：baseURL 设为 /files，避开根路径 /api/ 的占用
- Nginx Proxy Manager 反代，额外转发 /files/api/ 并剥离前缀
- 写了 Python 修复脚本，把停服、CLI 改配置、验证串成一条流程
- 与量化研究服务共用一台机器，互不干扰
Stack: Docker · FileBrowser · Nginx Proxy Manager · Python · Nginx 反向代理 · CLI
1. Start the container
Run it with Docker. Pay attention to two things: both the data directory and the database must be mounted out—don’t leave the database inside the container.
- Mount the data directory to
/srvinside the container - Mount the database file separately (in my case,
/opt/web/filebrowser.db) - Map the port to the host and expose it externally via Nginx Proxy Manager
2. Set baseURL first—don’t wait for something to break
If you plan to put FileBrowser under a subpath (I put it at /files), the first thing to do is set the container’s baseURL to /files. Otherwise, the frontend will send login requests to the root path /api/login—if that path is already occupied by another service, login will keep failing.
Setting baseURL must be done through the official CLI, and the CLI requires exclusive access to the database, so stop the service first:
docker stop filebrowser- Use
docker run --rm --entrypoint filebrowserto start a one-off container, mount the database, and run the CLI’s config set to write baseurl (map the database path to the mount point recognized by the CLI) docker start filebrowser
This step causes brief downtime; do it when no one is using it.
3. Nginx reverse proxy
In Nginx Proxy Manager, add a proxy host pointing to FileBrowser’s port; then add a forwarding rule for /files/api/ that strips the /files prefix when forwarding and lands on FileBrowser’s /api/.... This way, the root path’s /api/ remains reserved for quantitative research, and the two don’t conflict.
4. Verification
Don’t just check whether the homepage opens; verify two things:
- The login endpoint is reachable, and you can log in normally
/api/endpoints of other services on the same machine are unaffected
I wrote a Python script that strings together stopping the service, changing the config, and verification into one flow; when reinstalling, just run it once.
