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_KEYinjected via secrets manager (not baked into image). -
keys.yamlmounted 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.
Related
- Pricing → — plan comparison.
- Errors → — same error catalog as SaaS.
- Performance → — self-host typically beats SaaS by 10–30%.
Something unclear or missing on this page?