Self-host

Run the gpdf-api binary on your own infrastructure. Same engine, same `/v1` surface, no quota, no watermark.

Self-host

Same code, your infra. The Self-host binary serves the exact same /v1 API as https://api.gpdf.dev. You skip our quota system; you bring your own.

What you get

  • A single Linux binary (~60 MB), no external dependencies.
  • The same JSON template grammar.
  • The same response headers (minus rate-limit ones — your reverse proxy owns that).
  • No watermark, ever.
  • No 5/15 MB response cap.

What you don't get

  • Our quota system. You enforce QPS / bandwidth caps in your own reverse proxy.
  • The dashboard. Self-host has no UI; manage keys/certs through the binary's REST surface.
  • Polar-managed billing.
  • Multi-region SLA. You run wherever you want.

Pricing

$79/month per production instance, billed via Polar. A single license key allows up to N concurrent active instances (N is set on your subscription). Each running instance phones home once a day to refresh a JWT.

If your infra fans out beyond what your subscription allows, the extra instances will fail to start. Contact sales@gpdf.dev for higher seat counts.

Quickstart

docker run -d \
  -p 8080:8080 \
  -e GPDF_API_LICENSE_KEY=gpdfl_abc1234... \
  -e GPDF_API_LISTEN=0.0.0.0:8080 \
  --name gpdf-api \
  ghcr.io/gpdf-dev/gpdf-api:1.0.4

The container exposes the same routes as https://api.gpdf.dev. Verify with:

curl http://localhost:8080/health
# {"status":"ok"}

Environment variables

Var Required Default Notes
GPDF_API_LICENSE_KEY yes — gpdfl_… from the dashboard.
GPDF_API_LISTEN — 0.0.0.0:8080 Host:port to bind.
GPDF_API_KEYS_FILE — /etc/gpdf/keys.yaml Path to your API-key store (see below).
GPDF_API_LOG_LEVEL — info trace, debug, info, warn, error.
GPDF_API_LICENSE_HEARTBEAT_URL — https://api.gpdf.dev/v1/license Override only for support-driven failover.
GPDF_API_HTTP_PROXY — — If your network requires an outbound proxy for the heartbeat.
GPDF_API_FONTS_DIR — — Path to a directory of .ttf/.otf files. They're picked up at startup; family name is the filename.
GPDF_API_PDFA_DEFAULT — — 1a, 1b, 2b, 2u, or empty. Default for requests without options.pdfa.

Authentication

Self-host doesn't use Firebase. You manage your own API keys in a local YAML file:

# /etc/gpdf/keys.yaml
keys:
  - prefix: gpdf_a1b2c3d4
    hash:   sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
    label:  production

  - prefix: gpdf_x9y8z7w6
    hash:   sha256:0a4d55a8d778e5022fab701977c5d840bbc486d0
    label:  staging
    revoked: true

Each entry must have prefix (12 chars matching gpdf_[a-z0-9]{8}) and hash (SHA-256 of the raw key, hex-encoded, prefixed with sha256:). The raw key never lives on disk — only its hash.

To generate a key + hash pair:

docker run --rm ghcr.io/gpdf-dev/gpdf-api:1.0.4 keygen
# raw=gpdf_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
# prefix=gpdf_a1b2c3d4
# hash=sha256:e3b0c44...

Save the raw key in your secrets store and add prefix + hash to keys.yaml. Hot-reload by sending SIGHUP:

docker kill -s HUP gpdf-api

License heartbeat

On startup, the binary calls POST /v1/license/verify with its GPDF_API_LICENSE_KEY. Successful response returns a JWT valid for 24 h. Every 24 h the binary refreshes via POST /v1/license/heartbeat.

If the heartbeat fails for more than 24 h, the binary refuses new renders (returns 503 license_unverified) until it can re-validate. There is a 48 h emergency grace during incidents on our side; the status page is the canonical source.

container start ─▶ verify (1 call) ─▶ JWT valid 24h
                                       │
                                       ├──▶ render render render … (no further calls)
                                       │
                                       ╰──▶ at 23h: heartbeat ─▶ JWT renewed

Outbound traffic from the binary is exclusively to your configured GPDF_API_LICENSE_HEARTBEAT_URL (default https://api.gpdf.dev). All other API surfaces are inbound-only.

Reverse-proxy patterns

The binary doesn't enforce rate limits — that's your job. A typical Nginx config:

limit_req_zone $http_authorization zone=gpdfkey:10m rate=20r/s;

server {
    listen 443 ssl http2;
    server_name pdf.internal.example;

    location / {
        limit_req zone=gpdfkey burst=40 nodelay;
        proxy_pass http://gpdf_api_upstream;
        proxy_set_header Host $host;
        proxy_request_buffering off;   # important — stream the response
        proxy_buffering off;
    }
}

proxy_buffering off is important — the binary streams the PDF body as it's generated. Buffering inflates time-to-first-byte and memory.

Production checklist

  • GPDF_API_LICENSE_KEY injected via secrets manager (not baked into image).
  • keys.yaml mounted from a secrets volume; never copied into the image.
  • Outbound HTTPS to the license endpoint allowed.
  • Reverse proxy (Nginx, Cloud Run, ALB) with proxy_buffering off.
  • Per-key rate limiting in the proxy.
  • Monitoring on /health (every 10–30 s).
  • Log shipping for stdout (the binary logs structured JSON).
  • Renewal alerting before your subscription expires.

Upgrades

We publish a new 1.x.y Docker tag for every minor release. Pin to a tag in production; never :latest. Migration notes for breaking changes (only at major bumps) ship with each release on GitHub.

# Pin
docker pull ghcr.io/gpdf-dev/gpdf-api:1.0.4

# Roll forward (blue/green or rolling)
docker tag ghcr.io/gpdf-dev/gpdf-api:1.0.5 gpdf-api-current

Differences from SaaS

SaaS Self-host
Watermark on Free yes no (no Free tier)
Quota account-level monthly none — you enforce
Rate limit per-key bucket none — you enforce
X-GPDF-Quota-* headers yes omitted
Sandbox endpoint yes yes
Auth API key (Firestore) API key (keys.yaml)
Dashboard yes none
License implicit mandatory gpdfl_…
Region us-central1 yours

Common questions

"Can I read the source?" The engine (gpdf) is MIT-licensed Go. You can read every line. The SaaS layer (gpdf-api) — auth, quota, billing, logging — is closed source, but the binary is what you run.

"What if I want airgap?" Not at v1. The license heartbeat needs an outbound HTTPS call once a day. Talk to us if your environment forbids any outbound — we have a roadmap for offline activation.

"Can I bake the license into a Docker image?" Don't — it's a secret. Use Docker secrets, AWS Parameter Store, GCP Secret Manager. Anything that mounts at runtime, not build time.

Something unclear or missing on this page?