Configuration Files (v1.5.x)

What is a Config File? link

A configuration file (config file) is a YAML file that defines how FileBrowser Quantum should work. While FileBrowser can run without a config file using default settings, a config file is generally necessary and allows you to customize:

• Server settings (port, database location, sources)
• Authentication methods (password, OIDC, proxy)
• User management and permissions
• Frontend customization (themes, branding)
• Media and office integrations

See an example config file on Github.

How to Specify a Config File link

FileBrowser looks for configuration in the following order of priority:

1. Command Line Argument link

1

./filebrowser -c /path/to/config.yaml

2. Environment Variable link

1
2

export FILEBROWSER_CONFIG="/path/to/config.yaml"
./filebrowser

3. Default Locations link

• Current directory (./config.yaml)
• Docker default: /home/filebrowser/data/config.yaml

Database Path Configuration link

The database path is configured in the server.database setting. See Server configuration for details.

Default database locations:

• Standalone: ./database.db (current directory)
• Docker: first checks /home/filebrowser/data/database.db, then ./database.db (current directory)

Priority for database path:

1. Path specified in config.yaml via server.database
2. Default location based on deployment type (standalone vs Docker)

Docker Configuration link

Using Docker Run link

1
2
3
4
5
6

# Mount your config file
docker run -d \
  -v /path/to/your/config.yaml:/home/filebrowser/data/config.yaml \
  -v /path/to/your/folder:/folder \
  -p 80:80 \
  gtstef/filebrowser:stable

Using Docker Compose link

1
2
3
4
5
6
7
8
9

services:
  filebrowser:
    volumes:
      - '/path/to/folder:/folder'
      - './data:/home/filebrowser/data'
    ports:
      - '80:80'
    image: gtstef/filebrowser:stable
    restart: unless-stopped

Basic Configuration Example link

Here’s a minimal config file to get you started:

1
2
3
4
5
6
7
8
9

server:
  sources:
    - path: "/path/to/your/files" # or '/folder' in above example (do not load the full os filesystem, must be sub path)
      config:
        defaultEnabled: true  # Give access to all users by default

auth:
  adminUsername: admin
  adminPassword: admin

Configuration Options link

FileBrowser supports extensive configuration options. You can view the complete configuration reference at:

• Full config example: Full Config Example
• Current config: In the web UI, Admins can go to Settings > System & Admin > Load Config

Key Configuration Sections link

• Server Settings: Port, database, sources, caching
• Authentication: Password, OIDC, proxy authentication
• UsersDefaults: New user defaults
• Frontend: UI customization, themes, branding
• Integrations: Media (FFmpeg) and office (OnlyOffice) support

Best Practices link

1. Keep It Simple link

Only configure the settings you need. A minimal config is easier to read and maintain:

1
2
3
4
5
6
7
8

server:
  sources:
    - path: "/data"
      config:
        defaultEnabled: true

auth:
  adminUsername: admin

2. Use Environment Variables for Secrets link

Instead of putting secrets in your config file, use environment variables:

1
2
3
4

auth:
  methods:
    oidc:
      enabled: true

And set environment variables:

1
2
3

FILEBROWSER_ADMIN_PASSWORD="mysecurePassword"
FILEBROWSER_OIDC_CLIENT_ID=exampleID
FILEBROWSER_OIDC_CLIENT_SECRET=exampleSecret

3. Restart After Changes link

Configuration changes require a restart to take effect:

1
2
3
4

# Stop FileBrowser
# Edit your config.yaml
# Start FileBrowser again
./filebrowser -c config.yaml

Next Steps link

• Configuration Overview - Complete configuration guide
• Full Configuration Reference - All available options
• Source Configuration - Configure file sources
• Authentication Setup - Set up authentication methods