Pulp Engine — Evaluator Guide

A quick orientation for engineering leads and technical teams evaluating Pulp Engine.

What Pulp Engine is

Pulp Engine is a self-hosted document rendering platform for developers. POST a template key and JSON data to the REST API; get back a PDF — from any language or stack, with no client SDK to install.

Templates are built in a browser-based visual editor that ships with the platform. The full render pipeline — Handlebars field mapping, JSON Schema validation, HTML generation, and Chromium-based PDF export — runs server-side on your own infrastructure.

Who it is for

Engineering teams that need reliable, repeatable document generation as part of their product or internal workflows.
Teams that want self-hosted control over the render pipeline — no SaaS dependency.
Operators comfortable running containers, setting environment variables, and managing their own infrastructure.

Who it is not for

Business users who need drag-and-drop report building without developer involvement.
Platforms where untrusted, anonymous users author templates directly. Multi-tenant deployments are supported (opt-in, Postgres or SQL Server), but every tenant’s template authors are still assumed to be credentialled internal users — Pulp Engine is not designed for hostile-author environments.
Teams looking for a polished no-code SaaS product with managed hosting.

Current status

Pulp Engine is pre-1.0 and actively developed. It is used in the author’s own deployments and is suitable for controlled internal trials by technical teams who can verify fitness against their own workload. There is no broad external production adoption yet.

Deployment-readiness evidence (repo-verifiable):

Hardened production defaults enforced at startup (NODE_ENV=production)
Three supported storage backends: PostgreSQL, SQL Server, file-backed
Docker production image with GHCR CI pipeline, SBOM, and vulnerability scan
Scoped API credentials, named-user audit identity, queryable audit event log
Render isolation: child-process (default), container, and socket modes
Unit, integration, file-mode, SQL Server, and Playwright E2E suites, all hard-gated in CI (ci.yml)
Prometheus metrics, structured JSON logging, health/readiness probes

Best fit today: technical teams evaluating self-hosted document generation for controlled internal adoption.

Fastest way to evaluate

The Docker Compose quick start runs Pulp Engine in file mode with no database. It takes under a minute.

cp .env.file-mode.example .env
# Edit .env — set API_KEY_ADMIN and API_KEY_EDITOR
docker compose up -d

Then:

Open the visual editor at http://localhost:3000/editor/ and sign in with your API_KEY_EDITOR.
Create a template — add text, tables, images, conditionals, or use the starter templates.
Preview the template in the editor (live HTML preview is enabled by default).
Call the render API from any HTTP client to generate a PDF:

curl -s -X POST http://localhost:3000/render \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-admin-or-render-key>" \
  -d '{ "template": "<your-template-key>", "data": { ... } }' \
  --output output.pdf

Inspect the PDF. Check field mapping, pagination, table headers, and conditional sections.

For a guided API walkthrough with ready-made payloads, see demo-guide.md.

What to evaluate during a serious trial

Area	What to look at
Editor workflow	Template authoring across 24 content node types (including pivotTable, barcode/QR, richText, chart, templateRef, toc, positioned); 28 built-in starting points in the new-template dialog (Blank + 27 tabbed packs across 5 categories: general, financial, commercial, hr, operations); visual JEXL expression builder; Handlebars playground; per-node comments; node templates/favorites; collapsible property groups; preview fidelity; publish behavior; version history with compare/restore; labels (`stable`, `draft`, A/B variants)
Render API	`POST /render` (PDF), `/render/html`, `/render/docx`, `/render/pptx`, `/render/csv`, `/render/xlsx`, `/render/batch`, `/render/validate`, PDF-transform utilities (merge/watermark/insert), validation errors, OpenAPI spec at `/docs`
Deployment model	Storage backends (Postgres, SQL Server, file), Docker images, hardened production mode, render isolation (`RENDER_MODE=in-process` / `child-process` / `container` / `socket`)
Auth and trust	Scoped API credentials (`admin`/`render`/`preview`/`editor`), named-user mode, HMAC editor session tokens, OIDC/SSO with PKCE, audit logging with actor attribution
Multi-tenancy (opt-in)	`MULTI_TENANT_ENABLED` isolation of templates, assets, credentials, audit events, and schedules; super-admin `/admin/tenants` CRUD — see tenant-isolation-guarantees.md
Asset handling	Image upload, inline rendering, S3-compatible object storage option, private asset access mode
Scheduled delivery	Cron-driven renders with email / S3 / webhook targets; DLQ inspection endpoints
AI template generation	`POST /templates/generate` — schema-constrained Claude tool-use; opt-in via `ANTHROPIC_API_KEY`. Claude emits sample data alongside the template in a single tool call, persisted as a versioned sub-resource: `GET` / `PUT` / `DELETE /templates/:key/sample` for subsequent round-trips
Extensibility	Plugin system (custom nodes, renderers, routes, hooks); `<pulp-engine-editor>` embeddable editor custom element for in-product integration
Operational surface	Health probes (`/health`, `/health/ready`), Prometheus metrics, structured JSON logging, `X-Request-ID` correlation, `/capabilities` introspection, render-usage analytics

Deployment boundaries and trust assumptions

Trusted-tenant model. Templates and Handlebars helpers are authored by credentialled internal users — the render pipeline runs a headless Chromium instance, so template authoring must be limited to trusted team members. Multi-instance deployments are supported (Postgres + S3). The opt-in MULTI_TENANT_ENABLED mode (Postgres or SQL Server) provides per-tenant isolation of templates, assets, credentials, audit events, and schedules for operators running the platform on behalf of distinct internal business units or customers — see tenant-isolation-guarantees.md. Template authors in every tenant are still assumed credentialled; Pulp Engine is not designed for hostile-author environments. This is a design boundary, not a roadmap limitation.
Self-hosted, operator-managed. You provision infrastructure, configure credentials, handle upgrades, and control the deployment. There is no managed-hosting option.
Operator-managed audit identity. Named-user mode (EDITOR_USERS_JSON or runtime /admin/users CRUD) provides per-user audit attribution: each editor session is cryptographically bound to a named actor. For external identity verification, OIDC/SSO (PKCE, auto-provisioning) is available — see oidc-guide.md.
Hardened production mode is on by default. When NODE_ENV=production, the server enforces all security controls at startup. Set HARDEN_PRODUCTION=false to opt out for evaluation. See the deployment guide.

What to read next

Document	What it covers
Deployment guide	Full production setup — env vars, storage backends, Docker, hardening, reverse proxy, multi-tenant configuration
API guide	Endpoint reference, authentication model, scoped credentials, error semantics, schedules, admin routes, capabilities, usage analytics
Editor guide	Visual editor capabilities, deployment modes, auth flow, known limitations
Demo guide	Hands-on API walkthrough with ready-made curl commands
OIDC / SSO guide	PKCE auth-code flow setup for Okta, Azure AD, Keycloak, Auth0
Tenant isolation guarantees	What multi-tenant mode does and does not isolate
Operator runbook	Rotation, revocation, DLQ replay, audit purge, upgrades
HA reference architecture	Horizontal-scale topology, shared state, known limitations
Backup & restore runbook	`pg_dump` + asset sync + `pulp-engine backup` CLI
CHANGELOG	Release history and milestone changes

← Back to docs index