Complete guide for running FileBrowser Quantum behind reverse proxies including nginx, Traefik, and Caddy with authentication, SSL, and performance optimizations.

Overview

FileBrowser Quantum separates public and private endpoints to work efficiently with reverse proxies:

  • Public endpoints (/public) - Designed for share access without reverse proxy authentication.
  • Cookie-based authentication - Requires proper Host header forwarding
  • Real-time features - SSE support with proper proxy configuration

Public Route Structure

FileBrowser Quantum includes a dedicated /public route that contains:

  • /public/api/ - Public API endpoints for share access (hash-based authentication)
  • /public/share/ - Share pages (can work with or without user authentication)
  • /public/static/ - Static assets (CSS, JavaScript, images)

Route Authentication Requirements

TEXT 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Private Routes (Require User Authentication):
├── /api/*              - Private API endpoints
├── /dav/*              - WebDAV access  
└── /swagger/           - API documentation

Public Routes (Hash-based or Optional Auth):
├── /public/api/*       - Public API (share hash authentication)
├── /public/share/*     - Share pages (optional user authentication)
└── /public/static/*   - Static assets (no authentication)

Other Routes:
├── /                   - Main UI (optional authentication)
└── /health             - Health check (no authentication)

When configuring your reverse proxy, you can:

  • Require authentication for /api/ and other private routes
  • Allow public access to /public/ routes for share functionality

Basic Requirements

Essential Headers

All reverse proxy configurations must include these headers:

YAML 
1
2
3
4

# Required headers for FileBrowser Quantum
proxy_set_header Host $host;                                  # Cookie domain scoping
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;  # IP chain
proxy_set_header X-Forwarded-Proto $scheme;                   # HTTP/HTTPS protocol

FileBrowser Configuration

Configure FileBrowser to work with your reverse proxy:

YAML 
1
2
3

server:
  baseURL: "/files"                          # Base path for reverse proxy
  externalUrl: "https://files.example.com"   # External URL (used when generated public links)

nginx Configuration

Minimal nginx configuration for FileBrowser Quantum:

NGINX 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

server {
    listen 80;
    server_name files.example.com;

    # Public endpoints (for shares - no reverse proxy auth required)
    # These routes use hash-based authentication internally
    location /files/public/ {
        proxy_pass http://filebrowser:8080/files/public/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }

    # Private endpoints (authentication required)
    location /files/ {
        proxy_pass http://filebrowser:8080/files/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
        client_max_body_size 10G;
    }
}

With Authentication Proxy

For environments using external authentication:

NGINX 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

server {
    listen 80;
    server_name files.example.com;

    # Authentication endpoint
    location = /auth/authorize {
        internal;
        proxy_pass http://auth.example.com:8080/authorize;
        proxy_pass_request_body off;
        proxy_set_header Content-Length "";
    }

    # Public endpoints (no auth)
    location /files/public/ {
        proxy_pass http://filebrowser:8080/files/public/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }

    # Private endpoints (with auth)
    location /files/ {
        auth_request /auth/authorize;
        auth_request_set $user $upstream_http_x_forwarded_user;

        proxy_pass http://filebrowser:8080/files/;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-User $user;
        proxy_buffering off;
        client_max_body_size 10G;
    }
}

Traefik Configuration

Basic Traefik labels for FileBrowser Quantum:

YAML 
1
2
3
4
5
6
7
8

# Basic routing
- "traefik.enable=true"
- "traefik.http.routers.filebrowser.rule=Host(`files.example.com`)"
- "traefik.http.services.filebrowser.loadbalancer.server.port=80"

# Public endpoints (no auth)
- "traefik.http.routers.filebrowser-public.rule=Host(`files.example.com`) && PathPrefix(`/public`)"
- "traefik.http.services.filebrowser-public.loadbalancer.server.port=80"

Caddy Configuration

Minimal Caddy configuration:

CADDY 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

files.example.com {
    # Public endpoints (no authentication)
    handle_path /public/* {
        reverse_proxy filebrowser:80 {
            header_up Host {host}
            header_up X-Forwarded-For {remote_host}
            header_up X-Forwarded-Proto {scheme}
        }
    }

    # Private endpoints (with authentication)
    handle /* {
        reverse_proxy filebrowser:80 {
            header_up Host {host}
            header_up X-Forwarded-For {remote_host}
            header_up X-Forwarded-Proto {scheme}
        }
    }
}

Upload Configuration

Essential settings for file uploads:

Nginx

client_max_body_size 10G;
proxy_buffering off;

Traefik

- "traefik.http.middlewares.filebrowser-buffering.buffering.maxRequestBodyBytes=0"

Caddy

reverse_proxy filebrowser:80 {
    header_up Connection {>Connection}
    header_up Transfer-Encoding {>Transfer-Encoding}
}

Server-Sent Events (SSE) Configuration

FileBrowser Quantum uses SSE for real-time features. Essential settings:

NGINX 
1
2
3
4
5
6
7

location /files/ {
    proxy_pass http://filebrowser:8080/files/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_buffering off;
}
  • Traefik should handle most of this automatically if is configured properly.

Authorization Header Handling

NGINX 
1
2
3
4
5
6
7

location /files/ {
    proxy_set_header Authorization "";  # Clear authorization header
    proxy_pass http://filebrowser:8080/files/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
}

Troubleshooting

Common Issues

Authentication Failures

Symptoms: Users can't log in, cookies not working.

Solution: Ensure Host header is properly forwarded:

NGINX 
1

proxy_set_header Host $host;
YAML 
1

- "traefik.http.services.filebrowser.loadbalancer.passhostheader=true"

Upload Failures

Symptoms: Large file uploads fail

Solution: Increase file size limit and disable buffering:

NGINX 
1
2

client_max_body_size 10G;
proxy_buffering off;

In traefik can be configured via middlewares

YAML 
1
2
3
4
5
6
7
8

http:
  middlewares:
    limit:
      buffering:
        maxRequestBodyBytes: 0
        maxResponseBodyBytes: 0
        memRequestBodyBytes: 0
        memResponseBodyBytes: 0

SSE Not Working

Symptoms: Real-time features not updating

Solution: Disable buffering

NGINX 
1

proxy_buffering off;

Via traefik middlewares:

YAML 
1
2
3
4
5
6
7
8

http:
  middlewares:
    limit:
      buffering:
        maxRequestBodyBytes: 0
        maxResponseBodyBytes: 0
        memRequestBodyBytes: 0
        memResponseBodyBytes: 0

Next Steps