Production operations

At a glance

This page is the checklist for taking NextPDF to production and keeping it there. It curates the manual: every item links to the page that carries the depth, so you verify here and read there. Work through Pre-deploy checklist before the first release. Revisit Upgrade cadence and Incident triage entry points as part of day-two operations.

Pre-deploy checklist

Confirm the runtime: NextPDF requires PHP >=8.4 <9.0. Composer refuses anything outside that window. See Installation.
Verify the six required extensions with php -m: ext-mbstring, ext-zlib, ext-intl, ext-gd, ext-curl, and ext-openssl. The installation page explains what each one does.
Run vendor/bin/nextpdf doctor for a one-shot environment check (PHP version, extensions, and font availability in one report).
Decide your rendering path before you size hardware. The in-process pipeline (writeHtml()) needs no extra service. Artisan, Gotenberg, and Cloudflare each add a browser or network service to operate. Use Choose your path to decide.
If you picked a renderer bridge, read its security-and-operations page before go-live. See Harden the renderer surface.
Bundle the fonts you render at build time, and only those. See Provision fonts in production.

Resource sizing

Size for the largest document you generate, not the average. getPdfData() builds the entire Portable Document Format (PDF) document in memory and returns it as one string.

Set worker or function memory from the serverless sizing guidance: a few-page document is comfortable at 512–1024 MB; image-heavy or many-page documents need more.
Set timeouts above the worst-case build time, with margin. Move oversized jobs to an asynchronous queue that writes to object storage — the same sizing section shows the pattern.
Give long-lived workers opcache with timestamp validation off. The Docker recipe’s opcache section carries the production ini values.
When memory or throughput drifts after launch, start from the symptom-to-lever decision table.

Worker-safety rules

A Document is single-use. Build it, write it once, and let it leave scope; create a fresh instance per request or per queue job. Share only the process-lifetime registries — FontRegistry and ImageRegistry — by creating them once at worker boot. This matches the per-request, per-job model of PHP-FPM, queue workers, and long-running application servers.

Recipe with the boot sequence and per-cycle reset: Worker-safe batch rendering.
The contract in one answer: Is it worker-safe and thread-safe?

Harden the renderer surface

Treat HTML as untrusted, especially anything user-influenced. Choose your path states the boundary: by default, the built-in pipeline runs no scripts and fetches no remote resources, while each bridge renders through a browser or a network service. Before exposing a bridge to production traffic, work through its security-and-operations page:

Artisan security and operations — the Chrome renderer surface.
Gotenberg security and operations — the Gotenberg service surface.
Cloudflare security and operations — the edge deployment surface.
Running the engine as a service? Add Connect security and operations.

Observability

NextPDF publishes no service-level objective (SLO) targets; derive yours from the render-duration and memory metrics you measure below.

Instrument the render path before the first incident, not after.

In-process engine: Observe with OpenTelemetry.
NextPDF Connect deployments: Connect OpenTelemetry recipe.
Per render, record: wall time, peak memory, page count, output size, and the outcome with its exception category from the error reference.
Alert on trends, not only failures: rising build times, rising peak memory, and timeout or memory-exhaustion counts are the leading signals in the memory and performance entries.

Upgrade cadence

Read the version support policy once, then hold releases to it. It defines the semantic-versioning contract, stability labels, the deprecation lifecycle, and the lifecycle vocabulary (active, lts, maintenance, frozen, eol) this manual uses.
Commit composer.lock so every deployed worker resolves the same engine version — the installation page states this discipline.
Review the changelog before each version bump.

Incident triage entry points

For a renderer-bridge incident (a Chrome crash, a Gotenberg outage, an edge-rendering failure), start from that bridge’s failure-modes section in Harden the renderer surface.

Start from the symptom, not the class name, in the troubleshooting knowledge base.
Map a caught exception to its category and context contract in the error reference.