Deploy and Host Gotenberg PDF API with Authentication on Railway

PDF conversion API with generated Basic Auth and private URL filtering.

About Hosting Gotenberg PDF API with Authentication

Deploying this template creates Gotenberg in your Railway project. The application receives an HTTPS domain automatically. Database and Redis services, when included, use private networking and generated credentials. The conversion API is stateless; save completed files in your own storage.

Why Deploy Gotenberg PDF API with Authentication on Railway

Official Gotenberg v8 image with Chromium and LibreOffice.
Basic Auth is enabled from the first launch with a generated password.
25 MB request limit, 60-second timeout and bounded conversion queues.
Outbound URL filters reject private IP destinations for conversion fetches and callbacks.

Common Use Cases

Generate invoices or reports from HTML.
Convert Office documents to PDF from an automation workflow.
Add PDF conversion to a backend without maintaining a browser runtime.

Dependencies for Gotenberg PDF API with Authentication

A Railway account and a plan with capacity for 1 service(s).
Included services: Gotenberg.
External integrations, mail delivery and your own business data are configured after installation as needed.

First launch

Deploy and wait for the /health check to pass.
Read GOTENBERG_API_BASIC_AUTH_PASSWORD from the service variables; the username is converter.
Call a conversion endpoint from your backend or automation platform using Basic Auth.
Send an HTML file to /forms/chromium/convert/html or an Office file to /forms/libreoffice/convert.

Example

Set the URL and credential variables locally to your own deployment values.

curl --fail --user "converter:$GOTENBERG_PASSWORD" --form files=@index.html "$GOTENBERG_URL/forms/chromium/convert/html" --output document.pdf

Operations

This is a stateless API, not a document management UI. Download returned PDFs into your own durable storage. Local files disappear when the request/container is removed. Private-network URL targets are blocked by default, so upload input files directly when converting internal documents. Large jobs may require more memory or lower concurrency.

Images are pinned to verified upstream image digests captured on 2026-10-17. Review upstream release notes, back up persistent data and update the image deliberately when upgrading. Railway charges the deployer for running services, storage and network usage.

Support and upstream

For Railway template wiring or deployment issues, use the discussion/support link on this template page. Include service names and redacted logs; omit passwords and tokens. Application documentation:

Configuration and authentication · Conversion API