schedule Published: October 17, 2024
update Last updated: October 17, 2024

What are Sources?

Sources are the directories that FileBrowser Quantum makes available to users. Each source represents a filesystem path that can be browsed, searched, and managed through the web interface.

Source Basics

Unique Paths Required

Each source must have a unique real filesystem path. FileBrowser uses the actual resolved path on the filesystem to identify sources internally, not the name you assign.

sources:
  - path: "/data"        # ✅ Valid
  - path: "/mnt/storage" # ✅ Valid - different path
  - path: "/data"        # ❌ Invalid - duplicate path

Source Names

Automatic naming: If you don’t specify a name, FileBrowser automatically assigns one based on the base folder name.

sources:
  - path: "/mnt/documents"  # Name: "documents"
  - path: "/data/photos"    # Name: "photos"

Custom naming: You can specify a custom display name:

sources:
  - path: "/mnt/documents"
    name: "Company Files"   # Custom name

Minimal Configuration

The simplest source configuration:

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

This creates a source that:

  • Is available to all new users
  • Has indexing enabled
  • Uses all default settings

Indexing Overview

Sources are indexed by default, which enables:

  • Search functionality - Fast full-text and filename search
  • Folder size calculations - Accurate directory size reporting
  • Folder previews - Thumbnail previews for image directories
  • Health monitoring - Source statistics and health information

Performance: Indexing uses adaptive scanning intervals based on filesystem complexity. For typical filesystems (under 50,000 items), expect scan times under 30 seconds with minimal memory usage (100-300MB). Larger filesystems may require more resources but benefit from smart interval adjustments that reduce scan frequency.

For detailed indexing information, see Understanding Indexing.

Configuration Options

path (required) 

path: "/data"

The filesystem path to the directory you want to serve. Can be absolute or relative, but must exist and be readable by FileBrowser.

name 

name: "My Files"

Display name shown in the UI. If not specified, uses the base folder name from the path. Useful for providing user-friendly names like “Company Files” instead of just “documents”.

defaultEnabled 

config:
  defaultEnabled: true

Whether new users automatically get access to this source. Defaults to false. Set to true for shared sources that all users should see.

denyByDefault 

config:
  denyByDefault: true

Deny access unless an explicit “allow” access rule exists. Defaults to false. Use this for high-security sources where access must be explicitly granted per user or group.

See Access Control Guide for more information.

private 

config:
  private: true

Designate source as private, which disables sharing. Defaults to false. Use this to prevent users from creating public shares for sensitive data.

defaultUserScope 

config:
  defaultUserScope: "/subfolder"

Default scope path for new users created automatically via API or CLI. Defaults to "/" (root of source). This restricts where new users can access within the source. Include the leading slash.

Works with createUserDir to place users in specific locations:

sources:
  - path: "/shared"
    config:
      defaultUserScope: "/users"
      defaultEnabled: true

New users will only see /shared/users and its subdirectories.

createUserDir 

config:
  createUserDir: true
  defaultUserScope: "/home"

Automatically create a directory for each new user. Defaults to false. When enabled:

  • Creates {defaultUserScope}/{username} on user creation
  • Updates user scope to their personal directory
  • Directory persists even if user is deleted

Example:

config:
  createUserDir: true
  defaultUserScope: "/home"

Creates /home/john for user “john” and sets their scope to that directory.

disabled 

config:
  disabled: true

Disable the source without removing it from config. Defaults to false. Useful for temporarily disabling a source for maintenance or testing. Users cannot access disabled sources.

disableIndexing 

config:
  disableIndexing: true

Completely disable indexing for this source. Defaults to false.

Only disable if you have specific performance requirements and don’t need search or size information.

indexingIntervalMinutes 

config:
  indexingIntervalMinutes: 30

Force a specific scan interval in minutes. Defaults to 0 which uses smart scanning.

When to use:

  • You need guaranteed scan intervals for compliance
  • Your filesystem has predictable, regular update patterns
  • Smart scanning doesn’t suit your specific workload

How it works: Performs 4 quick scans at the specified interval, then 1 full scan.

conditionals 

config:
  conditionals:
    ignoreHidden: true
    ignoreZeroSizeFolders: true
    rules:
      - folderPath: "excluded"
      - fileNames: ".DS_Store"

Control which files and folders are indexed. See Conditional Rules Guide for complete documentation.

ignoreHidden (default: false) - Skip all hidden files and folders during indexing. Hidden items won’t appear in search or UI.

ignoreZeroSizeFolders (default: false) - Skip folders with zero calculated size. Empty folders or folders containing only empty folders are ignored. You can still create folders via the UI; they must be populated by the next scan to remain visible.

rules - Array of conditional rules. See the Conditional Rules Guide for details.

Configuration Examples

Public Shared Source

A source available to all users with basic settings:

sources:
  - path: "/public"
    name: "Shared Files"
    config:
      defaultEnabled: true
      conditionals:
        ignoreHidden: true

User Home Directories

Automatically create isolated user directories:

sources:
  - path: "/home"
    name: "User Files"
    config:
      defaultEnabled: true
      defaultUserScope: "/"
      createUserDir: true
      conditionals:
        ignoreHidden: true
        ignoreZeroSizeFolders: true

Each user gets /home/{username} as their private space.

High-Security Source

Restrict access with explicit allow rules:

sources:
  - path: "/confidential"
    name: "Confidential"
    config:
      private: true           # No sharing allowed
      denyByDefault: true     # Require explicit access rules
      conditionals:
        ignoreHidden: true

Development/Media Source

Exclude common development artifacts and system files:

sources:
  - path: "/projects"
    name: "Projects"
    config:
      defaultEnabled: true
      conditionals:
        ignoreHidden: true
        ignoreZeroSizeFolders: true
        rules:
          - folderNames: "node_modules"
          - folderNames: "__pycache__"
          - folderNames: ".git"
          - folderEndsWith: ".cache"
          - fileNames: ".DS_Store"
          - fileNames: "Thumbs.db"

Archive Source with Minimal Rescanning

A source with large, rarely-changing archives:

sources:
  - path: "/archives"
    name: "Archives"
    config:
      defaultEnabled: false
      conditionals:
        rules:
          - neverWatchPath: "historical-data"
          - neverWatchPath: "backups-2020"

The neverWatchPath folders are indexed once but never rescanned, saving resources.

Mixed Visibility Source

Show certain folders in UI but exclude from search:

sources:
  - path: "/storage"
    config:
      conditionals:
        rules:
          - folderPath: "working"         # Fully indexed
          - folderPath: "archive"         # Hidden from UI and search
          - folderPath: "temp"
            viewable: true                # Visible in UI but not in search

Common Configuration Patterns

Single Shared Source

Use case: Simple shared file access

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

Multi-User with Personal Directories

Use case: Each user gets private space

sources:
  - path: "/home"
    config:
      defaultEnabled: true
      createUserDir: true

Departmental Sources

Use case: Multiple departments with access control

sources:
  - path: "/dept/sales"
    name: "Sales"
  - path: "/dept/engineering"
    name: "Engineering"

Use access rules to control who sees what.

Mixed Public/Private

Use case: Some sources public, others restricted

sources:
  - path: "/public"
    config:
      defaultEnabled: true
  - path: "/private"
    config:
      denyByDefault: true
      private: true

Best Practices

  1. Start Simple - Begin with minimal configuration and add options as needed
  2. Use Real Paths - Always use absolute paths for production deployments
  3. Plan Access Control - Design your access strategy before creating multiple sources
  4. Monitor Resources - Watch memory/CPU usage after adding sources with large filesystems

Next Steps