PDF configuration

Environment variables and deployment notes for @sumx/ssr-pdf.

Environment variables

Variable	Default	Description
`HTML_TO_PDF_MAX_CONCURRENT`	`2`	Max parallel renders (1–8) — see Render concurrency
`HTML_TO_PDF_DEBUG`	off	`1` / `true` / `yes` → request-scoped logs

Chromium / Puppeteer

Package depends on puppeteer (^23.x).
Production images must install Chromium dependencies (fonts, libc, etc.).
Portal Dockerfile includes a stage for PDF — mirror that for other services.

Common issues

Symptom	Fix
`Failed to launch browser`	Install Chromium deps; set `PUPPETEER_EXECUTABLE_PATH` if using system binary
Timeouts under load	Lower concurrency or increase CPU/memory
Blank PDF	Ensure `printBackground: true` for colored backgrounds; wait for webfonts

Docker

Build from kit or portal root with Chromium layer. Auth packages come from feed at image build; PDF only needs Node + Chromium at runtime.

See Docker (portal image) for PAT + feed install.

Dev test hosts (`dev-test-pdf-host`)


import { isDevTestPdfHostAllowedFromNodeReq } from '@sumx/ssr-pdf/dev-test-pdf-host';

Default allowlist for disposition: inline includes localhost, 127.0.0.1, and SumX dev hostnames. Override via createHtmlToPdfHandler({ isInlineDispositionAllowed }).

Security

Do not expose the PDF API without authentication in production unless explicitly product-approved.
Portal should gate /api/html-to-pdf behind session/BFF like other APIs.
Cap HTML size via route bodyParser + MAX_HTML_TO_PDF_LENGTH.