Reverse Proxy Guide

Reverse Proxy Setup

Sublarr runs on port 5765 and works behind any reverse proxy. This guide covers Nginx and Traefik.

---

Nginx

Basic Setup (HTTP)

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

    location / {
        proxy_pass http://sublarr:5765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    # WebSocket support (required for real-time updates)
    location /socket.io/ {
        proxy_pass http://sublarr:5765/socket.io/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_read_timeout 86400;
    }
}

With SSL (Certbot / Let’s Encrypt)

server {
    listen 443 ssl;
    server_name sublarr.example.com;

    ssl_certificate     /etc/letsencrypt/live/sublarr.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/sublarr.example.com/privkey.pem;
    ssl_protocols       TLSv1.2 TLSv1.3;
    ssl_ciphers         HIGH:!aNULL:!MD5;

    # Increase timeouts for large subtitle file uploads
    client_max_body_size 50M;
    proxy_read_timeout 300s;
    proxy_send_timeout 300s;

    location / {
        proxy_pass http://sublarr:5765;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto https;
    }

    location /socket.io/ {
        proxy_pass http://sublarr:5765/socket.io/;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto https;
        proxy_read_timeout 86400;
    }
}

# HTTP -> HTTPS redirect
server {
    listen 80;
    server_name sublarr.example.com;
    return 301 https://$host$request_uri;
}

Subpath Setup

location /sublarr/ {
    proxy_pass http://sublarr:5765/;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Prefix /sublarr;
    proxy_set_header X-Forwarded-Proto $scheme;
}

location /sublarr/socket.io/ {
    proxy_pass http://sublarr:5765/socket.io/;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

---

Traefik v2 / v3

Docker Labels

services:
  sublarr:
    image: ghcr.io/abrechen2/sublarr:latest
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.sublarr.rule=Host(`sublarr.example.com`)"
      - "traefik.http.routers.sublarr.entrypoints=websecure"
      - "traefik.http.routers.sublarr.tls.certresolver=letsencrypt"
      - "traefik.http.services.sublarr.loadbalancer.server.port=5765"
      - "traefik.http.middlewares.sublarr-ws.headers.customrequestheaders.X-Forwarded-Proto=https"

---

Authentik / Authelia (SSO)

To bypass SSO for the API (scripts):

bypass:
  - domain: sublarr.example.com
    resources:
      - "^/api/v1/.*$"

Important: Always exclude /socket.io/ from SSO forward auth — SSO middleware often strips WebSocket upgrade headers.

---

Header-Based Authentication (Trusted-Proxy Login)

When Sublarr’s built-in UI login is enabled, you can let a reverse proxy that already authenticates the user (Authelia, authentik, or any forward-auth setup) log the user straight into Sublarr. Instead of asking for the Sublarr password again, Sublarr trusts an identity header that the proxy injects after its own SSO succeeds.

A request is accepted when all of the following hold — otherwise it falls through to the normal login gate (this fails closed):

1. Header-based auth is enabled.
2. The direct peer IP of the request is inside the configured trusted-proxy allowlist.
3. The configured identity header is present and non-empty on the request.

Sublarr reads the direct TCP peer address (it does not apply ProxyFix or trust X-Forwarded-For for this check), so the allowlist must contain the IP of the proxy that connects to Sublarr, not the client’s IP.

Settings

Setting	Default	Effect
proxy_auth_enabled	false	Master switch for trusting a reverse-proxy identity header.
proxy_auth_trusted_ips	(empty)	Comma-separated IPs / CIDRs of the proxies allowed to assert an identity. Empty means never trust — the feature stays off even when enabled.
proxy_auth_header	Remote-User	Name of the identity header Sublarr reads (e.g. Remote-User, X-Forwarded-User, X-authentik-username).

Set these under Settings in the Sublarr UI. Bare IPs are treated as single hosts (/32 or /128); CIDR ranges such as 172.18.0.0/16 cover a whole Docker network.

Example (Authelia + nginx)

Have your proxy set the identity header on the hop to Sublarr and point the allowlist at the proxy:

location / {
    proxy_pass http://sublarr:5765;
    proxy_set_header Remote-User $remote_user;   # set by Authelia
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
}

Then set proxy_auth_enabled = true, proxy_auth_trusted_ips to the proxy’s IP or network, and proxy_auth_header = Remote-User.

Trust boundary — expose Sublarr only through the proxy

Sublarr trusts the identity header purely because the request arrived from an allow-listed IP — it cannot tell whether the header value was set by your proxy or forged by the client. Two rules are mandatory:

• Configure the reverse proxy to strip any client-supplied copy of the identity header on the public side and only set it on the proxy-to-Sublarr hop.
• Make sure Sublarr is reachable only through the proxy. If any other host inside the trusted IP range (for example another container on the same Docker network or a machine on the same LAN/VLAN) can reach Sublarr’s port directly, it can send the identity header itself and impersonate any user, bypassing login entirely.

---

API Key Authentication

When Sublarr is accessible from the internet:

SUBLARR_API_KEY=<API_KEY>

All API endpoints will require the X-Api-Key: <API_KEY> header.

---

Unraid Nginx Proxy Manager

1. Add a new Proxy Host
2. Domain: sublarr.your-domain.com
3. Scheme: http, Forward Hostname: container name or IP, Port: 5765
4. Enable Websockets Support checkbox
5. Add SSL certificate (Let’s Encrypt)

---

Common Issues

Real-time updates not working

The WebSocket connection to /socket.io/ is missing. Check:

• Nginx Upgrade and Connection headers are forwarded
• Traefik has WebSocket middleware applied
• Proxy read timeout is at least 300 seconds

413 Request Entity Too Large

client_max_body_size 100M;

502 Bad Gateway after wake from sleep

Sublarr uses a single Gunicorn worker. Increase proxy read timeout to 30s to avoid false 502 errors.