Deploy Gotenberg: Self-Hosted HTML, Word & Markdown to PDF API

Deploy and Host Gotenberg on Railway

Gotenberg is an open source PDF generation API. Send it HTML, a URL, Markdown, or a Word, Excel or PowerPoint file over a plain multipart HTTP request, and it sends back a PDF. Inside one container it runs headless Chromium for web content and LibreOffice for office documents, plus PDF tools to merge, split, flatten, watermark and convert to PDF/A. It is MIT licensed with about 13,500 GitHub stars, and v9.5.1 shipped in November 2026. This template runs it on Railway with basic auth turned on, a generated password, longer timeouts for big documents, and SSRF protection that stops the converters from fetching private network addresses. Hosted PDF APIs such as DocRaptor start at $15/month for 125 documents. Gotenberg on Railway costs about $10–20/month with no per-document fees.

What This Template Deploys

There is no database and no volume. Gotenberg is stateless: every request carries its own files and gets back its own PDF, so redeploys lose nothing.

About Hosting Gotenberg

Generating PDFs inside your own app usually means bundling a headless browser, fighting fonts, and keeping LibreOffice alive in a worker. Gotenberg moves all of that into one service that any language can call with curl or a form upload.

HTML and URL to PDF. The Chromium routes render a full web page, an HTML file with its CSS, images and fonts, or a remote URL. You control paper size, margins, landscape mode, headers and footers, page ranges, scale and print backgrounds, and you can wait for a JavaScript expression or a delay before printing.

Markdown to PDF. Upload an HTML wrapper plus Markdown files and Gotenberg renders them through Chromium, which suits invoices, reports and docs pages.

Office to PDF. The LibreOffice route converts more than 100 formats, including DOCX, XLSX, PPTX, ODT, RTF and plain text. Several files in one request can be merged into a single PDF.

PDF tools. Merge and split PDFs, rotate pages, add bookmarks, optimize file size, flatten forms, read or write metadata, encrypt with a password, attach files, and convert to PDF/A or PDF/UA for archiving and accessibility.

Screenshots. Chromium can also return a PNG, JPEG or WebP image of a page instead of a PDF, which is handy for previews and social cards.

Webhooks and async jobs. Add webhook headers to a request and Gotenberg returns at once, then posts the finished PDF to your URL. That keeps slow conversions out of your web request cycle.

Deploy Gotenberg in Under 5 Minutes

1. Click Deploy on Railway. The password is generated for you.
2. Wait for the health check on /health to pass. Chromium and LibreOffice warm up at boot, so the first start can take up to a minute.
3. Open the service's Variables tab and copy GOTENBERG_API_BASIC_AUTH_USERNAME and GOTENBERG_API_BASIC_AUTH_PASSWORD.
4. Test it: curl -u gotenberg:YOUR_PASSWORD --form url=https://example.com https://YOUR-DOMAIN/forms/chromium/convert/url -o example.pdf.
5. Call the same routes from your app, or point an existing Gotenberg client library at your Railway domain.

Common Use Cases

• Invoices and receipts: render an HTML template from your app and store or email the PDF.
• Reports and exports: turn dashboards, tables or Markdown into printable documents.
• Office conversions: convert uploaded Word, Excel and PowerPoint files to PDF for preview or archiving.
• Contracts and forms: merge pages, flatten form fields and add metadata before signing.
• Archiving: convert documents to PDF/A for long-term storage requirements.
• Link previews: capture screenshots of pages for thumbnails and social images.
• Workflow tools: call it from n8n, Zapier-style tools or serverless functions that cannot run a browser themselves.

Configuration

The start command also sets a 60-second start timeout, a 120-second request timeout, and the private IP deny flags for Chromium, LibreOffice, webhooks and remote downloads.

The SSRF guard. Because the deny flags are on, Gotenberg refuses to load private addresses, including *.railway.internal hosts. Send HTML in the request body instead of asking Gotenberg to fetch a URL inside your project. If you really need internal URLs, remove the matching flag from the start command and keep basic auth enabled.

Big documents. Raise --api-timeout in the start command and give the service more memory if large spreadsheets or long pages time out.

Scaling out. Gotenberg holds no state, so you can add Railway replicas and let the load balancer spread requests across them. Each replica runs its own Chromium and LibreOffice, so plan memory per replica rather than per request.

Async with webhooks. Set a Gotenberg-Webhook-Url header on a request to get an immediate response and the finished PDF posted to your endpoint later. The webhook target must be a public URL while the private IP guard is on.

Fonts. The official image ships common fonts, including Noto for many scripts. For brand fonts, reference them from your HTML with @font-face and include the font files in the same multipart request.

Gotenberg vs. Alternatives

DocRaptor's Prince engine is strong at print CSS, but you pay per document and send your data to a third party. Puppeteer works until your app needs LibreOffice too or the browser eats your web server's memory. Stirling-PDF is a great PDF toolbox for people, while Gotenberg is designed for code to call.

Dependencies for Gotenberg Hosting

• A Railway account. No database, volume or other service is needed.
• An HTTP client in your app, or one of the community client libraries for PHP, Go, Node.js, Python, .NET and Java.

Deployment Dependencies

• Gotenberg on GitHub: source code and releases
• Gotenberg documentation: every route and form field
• Gotenberg on Docker Hub: image tags

Implementation Details

The image follows the latest tag, so a redeploy picks up new releases; the current one is v9.5.1. Pin a tag such as gotenberg/gotenberg:9 if you want upgrades on your own schedule. Gotenberg runs under tini as PID 1 so zombie Chromium and LibreOffice processes are reaped. Chromium and LibreOffice start at boot rather than on the first request, so the first conversion is fast. The /health route stays open without a password so Railway's health check can reach it, and every conversion route needs basic auth.

Frequently Asked Questions

What is Gotenberg? An MIT-licensed, stateless API that converts HTML, URLs, Markdown and office documents to PDF using Chromium and LibreOffice.

How much does it cost to host Gotenberg? About $10–20/month on Railway depending on load and memory. There are no per-document fees.

How do I authenticate requests? Use HTTP basic auth with GOTENBERG_API_BASIC_AUTH_USERNAME and GOTENBERG_API_BASIC_AUTH_PASSWORD from the service's Variables.

Can Gotenberg convert Word files to PDF? Yes. Post DOCX, XLSX, PPTX or ODT files to /forms/libreoffice/convert and it returns a PDF.

Why can't it load my internal URL? The template blocks private IP addresses to prevent SSRF. Send the HTML in the request instead, or remove the deny flag.

Does Gotenberg store my documents? No. Files exist only for the length of the request, and nothing is written to a volume.

Why Deploy and Host Gotenberg 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 Gotenberg on Railway, you get a private, password-protected PDF API for HTML, Markdown and office files, without per-document fees or a browser inside your app.