--- title: "HTTP/2 shared rendering | Nutrient" canonical_url: "https://www.nutrient.io/guides/document-engine/configuration/http2-shared-rendering/" md_url: "https://www.nutrient.io/guides/document-engine/configuration/http2-shared-rendering.md" last_updated: "2026-05-26T19:07:59.784Z" description: "HTTP/2 shared rendering reuses a single rendering process across all tile requests on one connection, improving throughput for tiled viewing of large documents." --- # HTTP/2 shared rendering HTTP/2 shared rendering is a performance feature for tiled viewing of large documents (where the viewer loads a page as many small image tiles instead of one full page image). When you enable it, tile requests on the same TCP connection reuse a connection-scoped rendering process. This avoids repeating per-request setup such as authentication, file materialization, and worker checkout for every tile. The feature works on any reused connection, but it's designed for HTTP/2. This protocol enables a client multiplex many concurrent tile requests on one connection without head-of-line blocking, which makes shared rendering useful at scale. HTTP/1.1 keep-alive connections also reuse the rendering process, but requests are serialized on the wire, so the performance gain is smaller. ## When to enable it Enable shared rendering if your workload includes tiled viewing of documents, especially large documents. Common cases include: - Viewing documents in the dashboard or a Web SDK integration - Deployments behind an HTTP/2-capable proxy such as Caddy with `h2c` upstream - Viewers that pan, zoom, or paginate through pages often If you're not sure whether this fits your workload, refer to the [large documents](https://www.nutrient.io/guides/document-engine/configuration/large-documents.md) guide. ## Configuration These environment variables control shared rendering: | Variable | Default | Description | | ------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `HTTP2_SHARED_RENDERING_PROCESS_ENABLE` | `false` | Enables the shared rendering path for supported tile endpoints. | | `HTTP2_SHARED_RENDERING_PROCESS_CHECKOUT_TIMEOUT` | `5000` | Maximum time in milliseconds to wait when checking out a rendering worker for a session. | | `HTTP2_SHARED_RENDERING_PROCESS_CHECKIN_TIMEOUT` | `0` | Idle time in milliseconds that a worker can stay checked out between tile requests on the same connection before Document Engine returns it to the pool. Set a small positive value to keep workers checked out across short gaps in a zoom or scroll gesture. | If a request doesn't match one of the shared rendering tile endpoints, Document Engine sends it through the normal request path. Enabling this feature doesn't affect non-tile requests. ### Recommended setup - Terminate HTTP/2 in front of Document Engine, or use `h2c` between a proxy such as Caddy and Document Engine. This ensures tile requests are multiplexed onto a single upstream connection. - Make sure clients reuse a single connection for tile requests. Creating a new connection per request defeats the optimization, regardless of HTTP version. ## Compatibility Enabling `HTTP2_SHARED_RENDERING_PROCESS_ENABLE` changes only performance behavior. Response bodies, status codes, and error shapes stay the same. The API doesn't change, and clients don't need changes beyond reusing connections. ## Interaction with clustering If you also enable [clustering](https://www.nutrient.io/guides/document-engine/deployment/horizontal-scaling.md#clustering), tile requests stay cluster-aware. Document Engine resolves the owner node for a document and runs the rendering process on that owner. The client still receives the response on the connection it originally opened. This behavior is supported: - Tile requests for a given `document_id` go to the same owner node that handles other document-scoped requests for that document. - If ownership moves during a scale event, in-flight rendering processes can finish, and subsequent requests resolve to the new owner. - During graceful shutdown, Document Engine drains remote rendering processes before the node exits. You don't have to enable clustering to use shared rendering, and you don't have to enable shared rendering to use clustering. Enable them independently, or enable both together. ## Observability The shared rendering path emits telemetry events that you can export through your monitoring pipeline. Notable event names include: - `http2.stream.worker_checkout` - `http2.stream.render_tile` - `http2.stream.render_process.exists` - `http2.stream.render_process.new` Standard request logs and the `Sent 200 in...` timing line still apply. Refer to the [metrics reference](https://www.nutrient.io/guides/document-engine/monitoring/metrics-reference.md) and [logs](https://www.nutrient.io/guides/document-engine/monitoring/logs.md) guides for more information. ## Related configuration - [Large documents](https://www.nutrient.io/guides/document-engine/configuration/large-documents.md) — Refer to the large documents guide to plan upload and timeout settings before you enable shared rendering for large files. - [Horizontal scaling](https://www.nutrient.io/guides/document-engine/deployment/horizontal-scaling.md) — Refer to the horizontal scaling guide to understand how clustering changes routing for document-scoped requests, including tile requests. - [Configuration options](https://www.nutrient.io/guides/document-engine/configuration/options.md) — Refer to the configuration options guide for the full environment variable reference. --- ## Related pages - [Certificate trust settings](/guides/document-engine/configuration/certificate-trust.md) - [Cache configuration](/guides/document-engine/configuration/cache.md) - [How to configure custom fonts in Document Engine](/guides/document-engine/configuration/custom-fonts.md) - [Asset storage configuration](/guides/document-engine/configuration/asset-storage.md) - [Hold workers across short idle gaps such as zoom or scroll pauses:](/guides/document-engine/configuration/large-documents.md) - [Configuration options](/guides/document-engine/configuration/options.md)