Running behind a reverse proxy

Published: October 28, 2025

Last updated: May 22, 2026

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

info

FileBrowser Quantum is designed to work seamlessly behind reverse proxies with proper configuration. This guide covers all major proxy types with complete examples.

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)

info

The /public routes are designed to allow shares to function fully without requiring authentication at the reverse proxy level. This enables share links to work even when the reverse proxy requires authentication for other routes. Public routes also use stricter logging to prevent sensitive information leakage.

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;  # Client IP chain
proxy_set_header X-Forwarded-Proto $scheme;                   # HTTP/HTTPS protocol

info

Note: FileBrowser Quantum also supports X-Forwarded-Host as an alternative to the Host header for cookie domain scoping.

Client IP and trusted headers

info

This applies to version v1.4.x and later

FileBrowser uses the client IP for authentication rate limiting and failed-login lockout. When traffic passes through a reverse proxy, the connection address seen by FileBrowser is the proxy — not the end user — unless you forward the real client IP and tell FileBrowser to trust those headers.

Also, the IP that shows in logging will use the value from the proxy if these are set.

Configure your proxy to set X-Forwarded-For (recommended) or X-Real-IP, then enable the same headers in FileBrowser:

YAML
1
2
3
4
http:
  trustedHeaders:
    - X-Forwarded-For
    - X-Real-IP

Without http.trustedHeaders, every user appears to share the proxy’s IP. Rate limits and lockouts then apply to all clients behind that proxy collectively, not per user.

warning

Only add headers to http.trustedHeaders when FileBrowser is behind a proxy that controls these headers. If users can reach FileBrowser without going through your proxy, they can spoof X-Forwarded-For and bypass per-IP limits.

See HTTP settings: trustedHeaders and built-in authentication rate limiting for details.

FileBrowser Configuration

Configure FileBrowser to work with your reverse proxy:

YAML
1
2
3
4
5
6
7
8
server:
  baseURL: "/files"                          # Base path for reverse proxy
  externalUrl: "https://files.example.com/files"   # External URL (used when generated public links)

http:
  trustedHeaders:
    - X-Forwarded-For
    - X-Real-IP

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;
    }
}

info

The /public route allows shares to function without reverse proxy authentication. This means share links (/public/share/<hash>) will work even if you require authentication for other routes. The share itself may still require a password or user restrictions as configured in FileBrowser.

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;
    }
}

warning

When using external authentication, ensure your auth service sets the X-Forwarded-User header with the username. FileBrowser will use this for proxy authentication.

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

info

If your reverse proxy sets authorization headers, you may need to clear them for FileBrowser to avoid conflicts with its own authentication system.

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

HTTP Settings - Trusted headers and auth rate limiting
Proxy Authentication - Configure header-based authentication
Office Integration - OnlyOffice behind reverse proxy
Traefik Setup - Filebrowser + OnlyOffice behind traefik reverse proxy.

Configuration Files

Running behind a reverse proxy

Overview link

Public Route Structure link

Route Authentication Requirements link

Basic Requirements link

Essential Headers link

Client IP and trusted headers link

FileBrowser Configuration link

nginx Configuration link

With Authentication Proxy link

Traefik Configuration link

Caddy Configuration link

Upload Configuration link

Nginx

Traefik

Caddy

Server-Sent Events (SSE) Configuration link

Authorization Header Handling link

Troubleshooting link

Common Issues link

Authentication Failures

Upload Failures

SSE Not Working

Next Steps link

Overview

Public Route Structure

Route Authentication Requirements

Basic Requirements

Essential Headers

Client IP and trusted headers

FileBrowser Configuration

nginx Configuration

With Authentication Proxy

Traefik Configuration

Caddy Configuration

Upload Configuration

Server-Sent Events (SSE) Configuration

Authorization Header Handling

Troubleshooting

Common Issues

Next Steps