Running behind a reverse proxy (v2.0.0)

Published: October 28, 2025

Last updated: August 10, 2026

info

This guide is for v2.0.0 (beta). Config examples use http.baseURL and http.trustProxyHeaders.

Using v1.5.x or older? See the v1.5.x reverse proxy guide instead.

Complete guide for running FileBrowser Quantum v2.0.0 (beta) 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.

Proxy headers FileBrowser understands

When FileBrowser runs behind a reverse proxy, your proxy should set standard forwarding headers. FileBrowser must be told to honor them with http.trustProxyHeaders: true:

Client IP

FileBrowser uses the client IP for authentication rate limiting, failed-login lockout, and activity logging. Without header trust enabled, every user appears to share the proxy’s IP.

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

YAML
1
2
http:
  trustProxyHeaders: true

Scheme and host

Your proxy should also set X-Forwarded-Proto and X-Forwarded-Host. Forwarding alone is not enough — enable header trust or FileBrowser ignores them:

YAML
1
2
http:
  trustProxyHeaders: true

These affect HTTPS detection, cookie domain, OIDC redirect_uri, share URLs, and WebAuthn. Without trusting forwarded headers, FileBrowser sees http behind TLS-terminated nginx and OIDC redirects break.

Keep proxy_set_header Host $host in nginx. X-Forwarded-Host is used when the proxy strips or overwrites Host.

Proxy authentication username

If you use proxy authentication, your auth middleware sets a username header (commonly X-Forwarded-User). That header is configured separately — not via trustProxyHeaders or trustedHeaders:

YAML
1
2
3
4
5
auth:
  methods:
    proxy:
      enabled: true
      header: "X-Forwarded-User"

When proxy auth is enabled, FileBrowser accepts the configured header as the username. Only enable this when FileBrowser is unreachable except through your proxy.

warning

Only enable trustProxyHeaders 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-* and bypass per-IP limits.

See HTTP reverse-proxy headers 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
 9
10
http:
  baseURL: "/files"
  externalUrl: "https://files.example.com/files"
  trustProxyHeaders: true

auth:
  methods:
    proxy:
      enabled: true
      header: "X-Forwarded-User"   # only when using external auth; separate from trustProxyHeaders

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 (v2.0.0)

Docker (v1.5.x)

Running behind a reverse proxy (v2.0.0)

Overview link

Public Route Structure link

Route Authentication Requirements link

Basic Requirements link

Essential Headers link

Proxy headers FileBrowser understands link

Client IP link

Scheme and host link

Proxy authentication username 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

Proxy headers FileBrowser understands

Client IP

Scheme and host

Proxy authentication username

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