Skip to content

Configuration And Examples

Jump to bottom
Graham Steffaniak edited this page Jul 25, 2025 · 31 revisions

Configuring your application

Note

See full config example. I recommend only configuring the settings you need.

Tip

You can also use Environment Variables to specify secrets and config file path.

Server Config Examples

You will need to define a source for filebrowser to run, here's a minimal example

server
  sources:
    - path: "/path/to/source"
      name: optional-name
      config:
        defaultEnabled: true # this gives the source to all users by default.
auth:
  adminUsername: admin
  adminPassword: admin

Two source config:

server:
  port: 80
  sources:
    - path: "/path/to/source1" # defaults with name "source1"
    - path: "/path/to/source2" # defaults with name "source2"

default source configuration

There are 3 defaults to consider when configuring a source:

  1. What users get access to the source by default? This is configured via defaultEnabled config.
  2. What is the default user scope for a source? This is configured via defaultUserScope config. This is the default scope a user gets when a new user is created and the scopes aren't specified. However, when creating a user via the UI, you must define scopes, which mostly apply to API and CLI user creation.
  3. Should a user directory be automatically created? This is configured via the createUserDir config. The default is false; it needs to be set to true to automatically happen on user creation. When true, the defaultUserScope is the base directory.
    • if you change sources, the new source will create user directories in the scope given on startup if they don't exist.
    • the user scope gets modified to be the username sub directory.

Here is an example config for defaults, where source2 is the only default a user gets with a scope in a subfolder.

server:
  sources:
    - path: "/path/to/source1"
    - path: "/path/to/source2"
      config:
        defaultUserScope: "/subfolder" # include leading slash
        defaultEnabled: true
        createUserDir: true           # "/subfolder/username" directory will be created

Example advanced source config:

with more advanced config including exclusions

server:
  port: 80
  sources:
    - path: "/mnt/folder"
      name: "mysource" # optional, otherwise the source gets named the folder name
      config:
        disableIndexing: false # if set to true, nothing gets indexed but is still viewable in the UI
        exclude: # these items will be excluded from both the UI and indexing
          filePaths:
            - "myfile.txt"            # corresponds to "/mnt/folder/myfile.txt"
            - "subfolder/another.txt" # corresponds to "/mnt/folder/subfolder/another.txt"
          folderPaths:
            - "subfolder/ignoreMe"    # excludes exact folder path (only one folder)
          fileNames:
            - "ignoreMe.txt"          # excludes all files named this
          folderNames:
            - "ignoreAllFolders"      # excludes all folders named this
          fileEndsWith:
            - ".zip"                  # excludes any files that end with ".zip"
            - ".tar.gz"
            - "-hidden.jpg"
          folderEndsWith:
            - "-backups"              # excludes any folders that end with "-backups"

Auth config Examples

You can configure multiple auth methods via auth.methods, without any configuration it defaults to password auth:

auth:
  methods:
    noauth: false
    password:
      enabled: true
      minLength: 7  # set min password length requirement -- defaults to 5 if unset
      signup: false
    proxy:
      enabled: true
      header: "proxy-user"  # header which should container username
      createUser: true      # automatically creates user with default user properties

By default, the only configured Auth method will be password if not configured.

Media integration

integrations:
  media:
    ffmpegPath: "/usr/local/bin" # wherever you have both ffmpeg and ffprobe installed at

OpenID Connect configuration (OIDC)

Enabling OIDC on FileBrowser Quantum is easy and requires two main changes:

Firstly, you must add your OIDC provider information to the config.yaml, such as:

issuerUrl is the domain used to fetch the well-known endpoint. This can be different for each provider, but here are some common examples:

  1. Authentik/Authelia: https://domain.com/application/o/filebrowser/ where filebrowser is the name of the provider.
  2. Pocket ID: https://domain.com/ (see example)
auth:
  methods:
    password:
      enabled: false # set to false if you only want to allow OIDC
    oidc:
      enabled: true                              # whether to enable OIDC authentication
      clientId: "xxx"                            # client id of the OIDC application
      clientSecret: "xxx"                        # client secret of the OIDC application
      issuerUrl: "http://localhost/application/o/filebrowser/" # URL of the OIDC provider
      scopes: "email openid profile groups"             # scopes to request from the OIDC provider
      userIdentifier: "preferred_username"       # the attribute used as username. Default/typical is "preferred_username", can also be "email" or "username", or "phone"
      disableVerifyTLS: false        # disable TLS verification for the OIDC provider. This is insecure and should only be used for testing.
      logoutRedirectUrl: ""          # if provider logout url is provided, filebrowser will also redirect to logout url. Custom logout query params are respected.
      createUser: true               # create user if it does not exist
      adminGroup: "authentik Admins" # if set, OIDC will manage whether a user is `admin` or not.

Tip

If you want an automatic flow to your OIDC provider, you'll need to disable password auth so OIDC is the only option. Once there are no other login methods, filebrowser will automatically redirect to your provider login screen if the user isn't authenticated.

Then, the next step is to provide your OIDC provider such as Authelia or Authentik with a valid "callback URL" , so it can redirect a valid login back to filebrowser. Typically, this will be the external URL, but you may also provide an internal callback as well. An example callback URL would be https://localhost:8080/api/auth/oidc/callback, where localhost:8080 is your filebrowser domain.

Note, if you have a non-default baseURL defined in your filebrowser config or proxy, your callback should include that.

Example Authelia OIDC Authentication

      - client_id: xxx
        client_name: filebrowser
        client_secret: xxx
        public: false
        authorization_policy: two_factor
        scopes:
          - openid
          - email
          - profile
        grant_types:
          - 'authorization_code' # required
        redirect_uris:
          - https://files.example.com/api/auth/oidc/callback
        userinfo_signing_algorithm: none
        token_endpoint_auth_method: client_secret_basic

Advanced Index config example

Frontend Configuration Example

An example frontend configuration in your config.yaml:

frontend:
  name: "My FileBrowser"                  # display name
  disableDefaultLinks: false              # disable default links in the sidebar
  disableUsedPercentage: false            # disable used percentage for the sources in the sidebar
  externalLinks:
    - text: my home page                  # the text to display on the link  validate:required
      title: my home page                 # the title to display on hover
      url: https://domain.com/            # the url to link to  validate:required
  disableNavButtons: false                # disable the nav buttons in the sidebar
  styling:
    customCSS: "customstyles.css"         # if a valid path to a css file is provided, it will be applied for all users. (eg. "reduce-rounded-corners.css")
    lightBackground: "white"              # specify a valid CSS color property value to use as the background color in light mode
    darkBackground: "#141D24"             # Specify a valid CSS color property value to use as the background color in dark mode
    customThemes:                         # A list of custom CSS files that each user can select to override the default styling. if "default" is key name then it will be the default option.
      default:                            # by naming default, all logged-in users will see this theme by default
        description: The default theme
        css: "your-custom-theme.css"
Clone this wiki locally