Deploy and Host

PDF Renderer runs as a background service with url access via public and or private network. Supporting ipv4 and ipv6. Uses playwright, NPM, and headless chromium to accomplish its task.

About Hosting pdf-renderer

Just need to load it into railway, add a token variable, and fire away. Dockerfile takes care of everything else.

Common Use Cases

Writing CSS and rendering it in PDF. Replaces DomPDF as background PDF generator.

Dependencies for pdf-renderer Hosting

Playwright
NPM
Chromium

Implementation Details

Variable pdf-renderer.RENDERER_TOKEN pdf-renderer.RENDERER_TOKEN . You need to randomly generate a token for security.

PDF Renderer Service Integration Guide

The PDF Renderer is a serverless microservice powered by headless Chromium/Playwright. It converts complete HTML/CSS markup into print-ready PDF documents via a single HTTP POST request.

1. HTTP Endpoint Specification

Property	Value
Method	`POST`
Endpoint	`https://<YOUR-RENDERER-HOST>/render`
Headers	`Authorization: Bearer <PDF_RENDERER_TOKEN>` `Content-Type: application/json` `Accept: application/pdf`
Response	`200 OK` with raw `application/pdf` binary stream

2. JSON Request Payload

{
  "html": "<!DOCTYPE html><html><head><style>@page { size: letter portrait; margin: 0; } body { font-family: sans-serif; }</style></head><body><h1>Certificate</h1></body></html>",
  "options": {
    "printBackground": true,
    "preferCSSPageSize": true,
    "format": "Letter",
    "landscape": false
  }
}

Available Options

Option	Type	Default	Description
`printBackground`	`boolean`	`true`	Renders background colors, CSS gradients, and box borders.
`preferCSSPageSize`	`boolean`	`true`	Prioritizes `@page { size: ... }` defined directly in the CSS.
`format`	`string`	`"Letter"`	Standard paper formats: `"Letter"`, `"Legal"`, `"A4"`.
`landscape`	`boolean`	`false`	Rotates layout to landscape orientation.
`width` / `height`	`string`	—	Custom page dimensions (e.g., `"9.5in"` & `"4.125in"` for #10 envelopes).

3. HTML & CSS Guidelines

Self-Contained Styles: Place all CSS inside <style> tags in the <head>.

Page Dimensions (@page): Use standard CSS Paged Media syntax:

@page {
    size: letter portrait; /* or size: 9.5in 4.125in; */
    margin: 0;
}

Images & Signatures: Embed logos, seals, and signatures as Base64 Data URIs to eliminate external network requests:
```
<img src="data:image/png;base64,iVBORw0KGgo..." alt="Parish Seal" />
```

Page Breaks: Force breaks between multiple certificates or sheets:

.page-break {
    page-break-after: always;
    break-after: page;
}

4. Code Example (PHP / Laravel)

use App\Services\PdfRendererService;

// 1. Render your Blade template into HTML
$html = view('pdf.certificates.baptism', [
    'request' => $certificateRequest,
])->render();

// 2. Send HTML to the PDF microservice (handles auto-retries for scale-to-zero cold starts)
$pdfBinary = app(PdfRendererService::class)->render($html, [
    'printBackground'   => true,
    'preferCSSPageSize' => true,
]);

// 3. Return as a streamable PDF response in the browser
return response($pdfBinary, 200, [
    'Content-Type'        => 'application/pdf',
    'Content-Disposition' => 'inline; filename="certificate.pdf"',
]);

Why Deploy pdf-renderer on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying pdf-renderer on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.