Skip to main content

Reverse Proxy Configuration

In production, PRISM sits behind a reverse proxy (nginx, Apache, or Caddy) that handles TLS termination, static assets, and request routing.

warning

Your reverse proxy must strip the X-Prism-Bypass header from incoming requests. This header is used internally by PRISM to prevent render loops. If an external client sends it, they can bypass rendering entirely.

Nginx​

upstream prism {
    server 127.0.0.1:4000;
    keepalive 32;
}

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

    ssl_certificate     /etc/ssl/certs/example.com.pem;
    ssl_certificate_key /etc/ssl/private/example.com.key;

    # CRITICAL: Strip bypass header to prevent external bypass
    proxy_set_header X-Prism-Bypass "";

    # Forward real client info
    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;

    # Timeouts — allow time for Chrome rendering
    proxy_read_timeout 30s;
    proxy_connect_timeout 5s;

    # Proxy all requests to PRISM
    location / {
        proxy_pass http://prism;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
    }

    # Bypass PRISM for static assets (optional, for direct origin serving)
    location ~* \.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|wasm|map)$ {
        proxy_pass http://your-origin:3000;
    }
}

Apache​

<VirtualHost *:443>
    ServerName example.com

    SSLEngine on
    SSLCertificateFile    /etc/ssl/certs/example.com.pem
    SSLCertificateKeyFile /etc/ssl/private/example.com.key

    # CRITICAL: Strip bypass header
    RequestHeader unset X-Prism-Bypass

    # Forward real client info
    ProxyPreserveHost On
    RequestHeader set X-Forwarded-Proto "https"

    # Proxy to PRISM
    ProxyPass / http://127.0.0.1:4000/
    ProxyPassReverse / http://127.0.0.1:4000/

    # Timeouts
    ProxyTimeout 30
</VirtualHost>

Caddy​

example.com {
    # Strip bypass header
    request_header -X-Prism-Bypass

    reverse_proxy 127.0.0.1:4000 {
        header_up X-Forwarded-Proto {scheme}
        transport http {
            keepalive 30s
            keepalive_idle_conns 32
        }
    }
}

X-Prism-Variant for CDN Cache Keying​

When viewport-aware rendering is enabled, PRISM returns an X-Prism-Variant header with the value mobile or desktop. If you have a CDN layer between nginx and clients, add this header to your Vary response or use it as a CDN cache key component.

In nginx, pass it through:

location / {
    proxy_pass http://prism;
    proxy_http_version 1.1;
    proxy_set_header Connection "";

    # Pass X-Prism-Variant to CDN for cache keying
    add_header Vary "X-Prism-Variant" always;
}

See CDN Integration for CDN-specific configuration.

Trusted Proxies​

When PRISM sits behind a reverse proxy, configure trusted_proxies so PRISM only accepts X-Forwarded-Proto from your proxy IPs:

[server]
trusted_proxies = ["127.0.0.1", "10.0.0.0/8", "172.16.0.0/12"]

When empty (the default), all proxies are trusted for backward compatibility.