Reverse Proxy Configuration

Since: 0.18.0

TL;DR

Phlix can run behind a reverse proxy (nginx, Caddy, or Apache) to terminate TLS, run in a subfolder, or load-balance across multiple instances. The server itself must be configured with the proxy's base URL so it generates correct absolute links.

Why Use a Reverse Proxy?

• TLS termination — terminate HTTPS at the proxy and forward plain HTTP to Phlix
• Subfolder deployment — host Phlix at https://example.com/phlix/ instead of root
• Load balancing — scale horizontally by proxying to multiple Phlix instances
• Firewall/NAT traversal — single port (8096) exposed through the proxy

General Requirements

When Phlix is behind a reverse proxy:

1. Set the TRUSTED_PROXIES environment variable (or trusted_proxies in config/server.php) to a comma-separated IP/CIDR list of every proxy hop in front of Phlix. The default is loopback only (127.0.0.1, ::1), which is correct for the stock install where nginx/HAProxy front Phlix over loopback — set this only when a non-loopback proxy is in the path.
2. Ensure the proxy forwards X-Forwarded-Proto, X-Forwarded-Host, and X-Forwarded-Port headers, and appends the real client to X-Forwarded-For (nginx $proxy_add_x_forwarded_for, HAProxy option forwardfor).

Rate-limit client-IP keying

TRUSTED_PROXIES is also what lets the built-in auth rate limiter derive the real client IP from X-Forwarded-For/X-Real-IP. If your non-loopback proxy hops are not listed here, every request buckets under the proxy's address (one abuser locks out everyone) or a client-forged X-Forwarded-For can dodge the limit. List each hop that fronts Phlix.

nginx Configuration

# /etc/nginx/sites-available/phlix
server {
    listen 443 ssl;
    server_name example.com;

    ssl_certificate     /path/to/fullchain.pem;
    ssl_certificate_key /path/to/privkey.pem;

    # Phlix runs on port 8096
    location /phlix/ {
        proxy_pass http://127.0.0.1:8096/;
        proxy_http_version 1.1;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Port $server_port;

        # WebSocket support (for live transcoding progress)
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

Subfolder Trailing Slash

When deploying to a subfolder, ensure the proxy_pass path ends with / so that /phlix/foo correctly maps to /foo on the upstream. Without the trailing slash, the location prefix is preserved in the upstream path.

Caddy Configuration

# Caddyfile
example.com {
    reverse_proxy /phlix/* localhost:8096
}

Caddy automatically handles WebSocket upgrades and X-Forwarded-* headers.

Apache Configuration

# /etc/apache2/sites-available/phlix.conf
<VirtualHost *:443>
    ServerName example.com
    SSLEngine on
    SSLCertificateFile /path/to/fullchain.pem
    SSLCertificateKeyFile /path/to/privkey.pem

    <Location /phlix>
        ProxyPass http://127.0.0.1:8096/
        ProxyPassReverse http://127.0.0.1:8096/
        RequestHeader set X-Forwarded-Proto "https"
        RequestHeader set X-Forwarded-Host "%{HTTP_HOST}s"
    </Location>

    # WebSocket support
    <Location /phlix/api>
        ProxyPass ws://127.0.0.1:8096/
    </Location>
</VirtualHost>

Phlix Server Configuration

Set the base URL so Phlix generates correct links:

// config/server.php
return [
    // ...
    'base_url' => getenv('BASE_URL') ?: 'https://example.com/phlix/',
    'trusted_proxies' => ['127.0.0.1', '::1'],
    // ...
];

Or via environment variable:

export BASE_URL=https://example.com/phlix/

Troubleshooting

Problem: Redirects go to the internal port instead of the proxy

Ensure trusted_proxies includes your proxy's IP and the X-Forwarded-* headers are being forwarded correctly.

Problem: WebSocket connections fail

Verify the Upgrade and Connection headers are being forwarded. The web interface uses WebSockets for live transcoding progress and real-time updates.

Problem: Mixed content warnings

Set X-Forwarded-Proto: https so Phlix generates HTTPS links when behind an HTTPS-terminating proxy.