Configuration Files (v2.0.0)

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. Environment variable substitution in YAML link

After the config file is loaded, string values in config.yaml may reference process environment variables using $VAR or ${VAR}. Expansion runs on the decoded YAML tree, so secrets can contain characters that would break unquoted YAML.

1
2
3
4

auth:
  methods:
    ldap:
      userPassword: "${FILEBROWSER_LDAP_USER_PASSWORD}"

When a scalar is only a single $VAR or ${VAR} reference, the expanded value may be coerced to a boolean or number when unambiguous (for example port: ${PORT}). Partial substitutions and ordinary strings stay strings.

Named FILEBROWSER_* variables in Environment variables still override matching config keys after expansion. Prefer those variables or ${VAR} in YAML for secrets rather than plaintext in the file.

4. Default Locations link

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

Database Path Configuration link

The database path is configured under server.database.path. See Server configuration for details.

Default database locations (v2.0.0+):

• Standalone, when neither config nor FILEBROWSER_DATABASE_PATH sets a path: ./filebrowser.sqlite
• Docker image, when config omits server.database.path: /home/filebrowser/data/database.sqlite (FILEBROWSER_DATABASE_PATH in _docker/Dockerfile)

Priority for database path:

1. server.database.path in config.yaml, when it is set
2. FILEBROWSER_DATABASE_PATH, when the config path is empty
3. filebrowser.sqlite

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 \
  ghcr.io/gtsteffaniak/filebrowser:beta

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: ghcr.io/gtsteffaniak/filebrowser:beta
    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
10

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  # Grant to all users on create; v2.0.1+ also merges for existing users on startup

auth:
  methods:
    password:
      enabled: true

On v2.x (v2.0.0+), if adminPassword is unset or left as admin, a random admin password is generated, logged once, and a password reset is required on first login. Any other value of auth.methods.password.adminPassword or auth.adminPassword is used as-is.

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