Skip to main content

Server Configuration

The [server] section controls how PRISM listens for incoming requests, connects to your origin application, and manages connections.

TOML Example​

[server]
address = "127.0.0.1:4000"
origin = "http://localhost:3000"
mode = "bot-only"
shadow = false
drain_timeout_secs = 30
proxy_timeout_secs = 30
trusted_proxies = ["10.0.0.0/8", "172.16.0.0/12"]
max_connections = 10000
max_request_headers = 100

Parameters​

ParameterTypeDefaultDescription
addressString"127.0.0.1:4000"Socket address PRISM listens on
originString"http://localhost:3000"URL of your application server
modeString"bot-only"Render mode: bot-only or render-all
shadowBooleanfalseShadow mode: render in background, serve origin response
drain_timeout_secsInteger30Seconds to wait for in-flight renders during graceful shutdown
proxy_timeout_secsInteger30Timeout in seconds for proxy requests to the origin
trusted_proxiesArray of Strings[]IP addresses/CIDRs whose forwarding headers are believed. Empty = trust none
max_connectionsInteger10000Maximum concurrent connections. 0 = unlimited
max_request_headersInteger100Most header fields one request may carry. Past it the connection is refused rather than buffered

Detailed Explanation​

address​

The IP and port PRISM binds to. Use 0.0.0.0:4000 to listen on all interfaces, or 127.0.0.1:4000 to restrict to localhost only.

origin​

The URL of your upstream application. All requests that do not require rendering (or all requests in proxy-only mode) are forwarded here. PRISM validates that this does not point to its own listen address to prevent infinite render loops.

mode​

  • bot-only (default): Only render pages for detected bot user agents. Human visitors are proxied directly to the origin.
  • render-all: Render every matching request through the headless browser, regardless of user agent. Useful for fully static SEO output.

shadow​

When enabled, PRISM renders pages in the background but always serves the origin response to the client. It logs comparison statistics (origin bytes vs. rendered bytes) for validation purposes. This is useful for testing PRISM in production without affecting real traffic.

drain_timeout_secs​

During graceful shutdown (e.g., SIGTERM), PRISM waits up to this many seconds for in-flight render operations to complete before forcefully terminating.

proxy_timeout_secs​

Maximum time to wait for a response from the origin server when proxying requests. If the origin does not respond within this window, PRISM returns a gateway timeout error.

trusted_proxies​

PRISM believes X-Forwarded-For and X-Forwarded-Proto only from these addresses, so a client cannot spoof either.

When empty — the default — nothing is trusted: both headers are ignored and the socket peer is treated as the client. That is the right default facing the internet directly, and the wrong one behind a proxy or CDN, where it resolves every visitor to the same edge address. The per-IP render limit (rate_limit_per_ip, three by default) then throttles all of your traffic as a single client. List your proxy's addresses and the real client address is recovered from X-Forwarded-For.

public_base_url​

The address visitors reach this instance at, when that differs from server.origin. Unset by default, in which case origin is used.

Set it whenever the origin is an internal name. Anything PRISM derives from the rendered page's URL — lazy-image data-src resolution in postprocessing above all — otherwise emits that internal address into HTML served to crawlers.

Since 1.4.0 it also pins X-Forwarded-Host. PRISM overwrites Host with the origin's own name, so the public one is passed along separately — and that value is whatever the client sent. A storefront deriving its base URL from it would build canonical links, redirects and sitemap entries pointing wherever the visitor asked. With public_base_url set, a Host that does not match it is replaced with the configured one.

Leave it unset if one instance legitimately serves several hostnames; PRISM then has nothing to check against and forwards the client's Host as before.

[server]
origin = "http://app-service:3000"
public_base_url = "https://shop.example.com"

max_request_headers​

Header count only. The total header bytes are bounded separately and are not configurable: 8 KiB plus 4 KiB per header, past which the request is answered 431 Request Header Fields Too Large. That same ceiling bounds the request target, because the URI is parsed out of the same buffer — there is no separate URL-length setting because there does not need to be one.

The default matches what the HTTP layer would have used anyway. It is stated explicitly so that a dependency upgrade changing that default cannot move this deployment's posture silently; tests/inbound_limits.rs checks what a socket actually refuses rather than what a constant says.

max_connections​

Limits the number of simultaneous connections PRISM accepts. Once the limit is reached, new connections are rejected. Set to 0 to disable the limit.

Example Use Cases​

Production behind a load balancer​

[server]
address = "0.0.0.0:4000"
origin = "http://app-service:3000"
mode = "bot-only"
trusted_proxies = ["10.0.0.0/8"]
max_connections = 5000

Testing with shadow mode​

[server]
address = "127.0.0.1:4000"
origin = "http://localhost:3000"
mode = "bot-only"
shadow = true

Full pre-rendering for all visitors​

[server]
address = "0.0.0.0:4000"
origin = "http://localhost:3000"
mode = "render-all"
proxy_timeout_secs = 15