Runbook: PDF Engine

Runbook: PDF Engine

Last updated: 2026-03-30 Service owner: ODS Platform Team Pipeline status: STAGING_VERIFIED

1. Service Overview

PDF Engine is a microservice for PDF generation and template management. It supports template CRUD with per-tenant isolation, PDF rendering from templates, and publishes events to Redpanda. Supports both RS256 (production) and HS256 (dev-only) JWT verification.

Property Value
Language Rust (Actix-web)
Container port 8080
DB schema pdf on ods database
Event bus topic events.pdf-engine
Coolify app UUID tgssoogso84sks80g0ckgg8w

2. Health Check

Endpoint: GET /health Expected response: HTTP 200

curl -sf https://pdf-engine.staging.orbusdigital.com/health

3. Staging URL

https://pdf-engine.staging.orbusdigital.com

4. Environment Variables

Variable Required Description
DATABASE_URL Yes postgres://ods:***@ods-postgres:5432/ods
HOST No Bind address (default 0.0.0.0)
PORT No Listen port (default 8082, exposed as 8080 in container)
JWT_RSA_PUBLIC_KEY Prod PEM-encoded RSA public key from OID
JWT_ISSUER Yes Token issuer URL
JWT_AUDIENCE Yes ods-pdf-engine
JWT_ALLOW_HS256 Dev only Set true for HS256 mode (NEVER in prod/staging)
JWT_SECRET Dev only HS256 secret (min 32 chars)
CORS_ALLOWED_ORIGINS No Comma-separated allowed origins
JSON_BODY_LIMIT_BYTES No Max JSON body size (default 1MB)
REDPANDA_BROKERS No Kafka broker (default in-memory)
REDPANDA_TOPIC No Event topic

5. How to Deploy

Via Coolify API

source ~/.env.adlc 2>/dev/null
curl -sf -X POST "https://app.coolify.io/api/v1/applications/tgssoogso84sks80g0ckgg8w/restart" \
  -H "Authorization: Bearer $COOLIFY_TOKEN"

Git-based deploy

Push to the staging branch of ljniox/pdf-engine. Coolify auto-deploys.

6. How to Check Logs

# On srv-staging (35.195.54.220):
docker logs --tail 200 -f $(docker ps -qf "label=coolify.applicationId=tgssoogso84sks80g0ckgg8w")

7. Common Issues and Fixes

Issue: Template uniqueness constraint violation

Symptom: HTTP 409 when creating a template with a name that already exists for the tenant.

Fix: This is expected behavior. Template names are unique per tenant. Use a different name or update the existing template.

Issue: JWT_ALLOW_HS256 accidentally enabled in staging

Symptom: Security review flags HS256 in staging.

Fix: Remove JWT_ALLOW_HS256 from Coolify env vars. Ensure JWT_RSA_PUBLIC_KEY is set to OID’s public key.

Issue: Large PDF generation timeout

Symptom: Request times out for complex templates.

Fix: Check container resource limits in Coolify. Consider increasing timeout or breaking the template into smaller sections.

8. How to Restart

docker restart $(docker ps -qf "label=coolify.applicationId=tgssoogso84sks80g0ckgg8w")

9. Dependencies

Dependency Type Details
PostgreSQL 17 Database ods-postgres:5432, schema pdf
Redpanda Event bus redpanda:9092, topic events.pdf-engine (optional)
OID Auth RSA public key or JWKS for JWT verification

10. Monitoring / Alerting