Self-Hosting Filebrowser on a VPS with Docker Compose

Filebrowser is a lightweight, single-binary web file manager that allows you to manage server directories through a clean, responsive web interface. When self-hosting on a VPS, a proper containerized deployment requires careful planning around directory bind mounts, multi-user permissions, secure networking, and data persistence. This guide walks through configuring Filebrowser using Docker Compose with best-practice patterns.

Directory Structure and Bind Mounts

Filebrowser requires a specific configuration pattern because it expects its database (filebrowser.db) and optional configuration file (settings.json) to exist on the host before the container starts. If these files do not exist, Docker will automatically create them as directories, which causes the container to fail to start.

Here is the recommended directory layout on the host VPS:

/opt/filebrowser/
├── docker-compose.yml
├── filebrowser.db
├── settings.json
└── data/

• filebrowser.db: An SQLite database file that stores user credentials, settings, share links, and folder permissions.
• settings.json: A JSON configuration file containing default application settings.
• data/: The root directory on your host containing the files you want to expose and manage.

Initialize the files on the host system before launching Docker Compose:

mkdir -p /opt/filebrowser/data
touch /opt/filebrowser/filebrowser.db

Configuring Multi-User Permissions and Ownership

Filebrowser runs inside the Docker container by default as the root user or a custom user depending on the image version. However, running containers as root poses security risks and can cause file ownership mismatches on the host (e.g., files uploaded via the web GUI become owned by root:root, preventing local non-root users from modifying them).

To handle permissions properly: 1. Identify the User ID (UID) and Group ID (GID) of the host user who should own the managed files: bash id Example output: uid=1000(debian) gid=1000(debian) 2. Map these IDs into the container using the user directive in your Docker Compose file. 3. Ensure the host user has read and write permissions to both the filebrowser.db database and the data/ directory.

chown -R 1000:1000 /opt/filebrowser/filebrowser.db /opt/filebrowser/data

Docker Compose Configuration

The following docker-compose.yml mounts the persistent database, configures settings, sets the user mapping, and exposes the service.

version: '3.8'

services:
  filebrowser:
    image: filebrowser/filebrowser:v2.32.0
    container_name: filebrowser
    user: "1000:1000"
    ports:
      - "127.0.0.1:8080:80"
    volumes:
      - /opt/filebrowser/data:/srv
      - /opt/filebrowser/filebrowser.db:/database/filebrowser.db
      - /opt/filebrowser/settings.json:/config/settings.json
    environment:
      - TZ=UTC
    restart: unless-stopped
    security_opt:
      - no-new-privileges:true

Key Configuration Directives:

• user: "1000:1000": Forces the containerized process to run as host user 1000 (UID) and group 1000 (GID).
• 127.0.0.1:8080:80: Binds the port to the local loopback interface. This prevents exposing Filebrowser directly to the public internet, requiring the use of a reverse proxy (e.g., Nginx, Caddy) to handle TLS/SSL encryption.
• /opt/filebrowser/data:/srv: Binds the host data directory to /srv, which is Filebrowser's default root directory inside the container.
• no-new-privileges:true: Security enhancement preventing the container's processes from gaining new privileges via setuid or setgid binaries.

Customizing Settings via JSON

If you want to configure global settings before the initial run, populate /opt/filebrowser/settings.json with the following configuration:

{
  "port": 80,
  "address": "0.0.0.0",
  "database": "/database/filebrowser.db",
  "root": "/srv",
  "log": "stdout"
}

Ensure this file is readable by the UID configured in Docker Compose:

chown 1000:1000 /opt/filebrowser/settings.json

Deployment Steps

Follow these execution steps to deploy Filebrowser:

1. Create the Project Directory and Files: bash mkdir -p /opt/filebrowser/data touch /opt/filebrowser/filebrowser.db
2. Create the Settings File: Write the default configuration to /opt/filebrowser/settings.json.
3. Write the Compose File: Write the docker-compose.yml block to /opt/filebrowser/docker-compose.yml.
4. Adjust Ownership: bash sudo chown -R 1000:1000 /opt/filebrowser
5. Start the Container: bash docker compose -f /opt/filebrowser/docker-compose.yml up -d
6. Verify the Logs: Verify that Filebrowser initialized the SQLite database correctly and is listening: bash docker compose -f /opt/filebrowser/docker-compose.yml logs -f

Post-Install Configuration and File Sharing

Upon initial deployment, Filebrowser creates a default administrator user with the credentials: - Username: admin - Password: admin

[!IMPORTANT] Change the default admin password immediately upon your first login under Settings > User Management.

Multi-User Management

Filebrowser provides granular, per-user access control. Administrators can create separate user accounts with customized permissions: - Scope: Lock a user to a specific subdirectory within /srv (e.g., /srv/user1). - Permissions: Toggle permission flags such as: - Create directories and files - Delete directories and files - Modify and write existing files - Download or share files - Execute command scripts on the host (should be disabled for security)

Secure File Sharing

Filebrowser allows generating sharing links directly from the Web GUI: 1. Hover or click on any file/folder and select Share. 2. Click Generate Link. 3. (Optional) Set an expiration time (e.g., 1 hour, 1 day) and configure an optional access password. 4. Secure links can be distributed to external users without exposing administrative controls or requiring system credentials.