Monitoring Gotenberg with Vigilmon

Gotenberg is an open-source Docker-based API that converts HTML pages, URLs, and Office documents to PDF using headless Chromium and LibreOffice. It's the engine behind invoice generation, contract rendering, and report pipelines in countless self-hosted stacks. But Gotenberg's built-in /health endpoint has a critical blind spot: it only confirms the Go HTTP server is running — it does nothing to verify that Chromium or LibreOffice are actually functional. A Chromium crash leaves /health returning {"status": "up"} while every PDF conversion silently fails. Vigilmon closes that gap with active conversion pipeline monitoring, SSL alerts for your ingress, and heartbeat checks that confirm the full rendering path end-to-end.

What You'll Set Up

• HTTP uptime monitor for the Gotenberg API health endpoint
• Active conversion monitor that tests Chromium's full rendering pipeline
• LibreOffice route monitor (for deployments that convert Office documents)
• SSL certificate expiry alerts for HTTPS Gotenberg deployments
• Cron heartbeat that catches Chromium crashes the /health endpoint misses

Prerequisites

• Gotenberg running as a Docker container (port 3000 by default)
• Gotenberg accessible over HTTP or HTTPS from the internet (or a public proxy in front of it)
• A free Vigilmon account

Step 1: Monitor the Gotenberg API Health Endpoint

Gotenberg exposes a built-in healthcheck at GET /health. Add a Vigilmon HTTP monitor for it as a baseline:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-gotenberg-host:3000/health
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Under Keyword check, enter "status":"up" to validate the response body.
7. Click Save.

This monitor catches cases where the Gotenberg HTTP server itself is down — container crashes, OOM kills, or port conflicts. It does not catch Chromium or LibreOffice failures.

Step 2: Monitor the Chromium Conversion Pipeline

The only way to confirm Chromium is actually converting documents is to send a real conversion request. Add an HTTP monitor that posts to the Chromium-based URL conversion route:

1. In Vigilmon, click Add Monitor → HTTP / HTTPS.
2. Set the URL to http://your-gotenberg-host:3000/forms/chromium/convert/url
3. Set Method to POST.
4. Set Content-Type to multipart/form-data.
5. Add a form field url with value https://example.com.
6. Set Expected HTTP status to 200.
7. Under Keyword check, enter application/pdf to confirm the response Content-Type is a valid PDF.
8. Set Check interval to 5 minutes.
9. Click Save.

A 200 response with Content-Type: application/pdf confirms that Chromium launched, rendered the page, and produced a PDF. If Chromium has crashed or is stuck, this request returns a 5xx error or times out — even while /health continues to return 200.

Note: If your Gotenberg deployment is behind an nginx reverse proxy, use the proxy's external URL rather than the container port directly.

Step 3: Monitor the LibreOffice Conversion Route

If your application converts Office documents (.docx, .xlsx, .pptx, .odt), the LibreOffice route needs its own monitor. LibreOffice and Chromium are managed as separate processes inside the Gotenberg container — one can fail while the other remains functional.

1. Add another Vigilmon HTTP / HTTPS monitor.
2. Set the URL to http://your-gotenberg-host:3000/forms/libreoffice/convert
3. Set Method to POST.
4. Set Content-Type to multipart/form-data.
5. Attach a minimal .txt file as the form body (Gotenberg accepts plain text files via LibreOffice).
6. Set Expected HTTP status to 200.
7. Add a keyword check for application/pdf.
8. Set Check interval to 5 minutes.
9. Click Save.

A successful response confirms LibreOffice is operational. Skip this monitor if your use case only uses Chromium-based HTML/URL conversion.

Step 4: SSL Certificate Alerts for HTTPS Deployments

Gotenberg is typically deployed behind an nginx reverse proxy that handles TLS termination. The SSL certificate on that ingress protects the multipart POST bodies containing your HTML content and generated PDFs. An expired certificate causes your application to fail generating PDFs at the worst possible moment.

1. Open the HTTP monitor for your Gotenberg proxy URL (created in Steps 2 or 3).
2. Enable Monitor SSL certificate in the SSL section.
3. Set Alert when certificate expires in less than 30 days.
4. Click Save.

A 30-day lead time gives you enough runway to renew via Let's Encrypt or your certificate authority before PDFs start failing in production.

Step 5: Heartbeat Monitoring for Chromium Crash Detection

The /health endpoint is the most critical monitoring blind spot in Gotenberg deployments. Chromium can crash silently — your GET /health probe keeps returning {"status": "up"} because the Go HTTP server is still running, but every PDF conversion attempt returns an error. The only reliable detection method is a scheduled conversion test that confirms Chromium is actually producing valid PDF output.

Set up a Vigilmon cron heartbeat:

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 65 minutes (slightly above the hourly test cadence to allow for execution time).
3. Copy the heartbeat URL: https://vigilmon.online/heartbeat/YOUR_TOKEN

Then configure a scheduled task on your server or in your CI/CD pipeline that runs every hour:

#!/bin/bash
# Scheduled Gotenberg conversion health check
set -e

GOTENBERG_URL="http://your-gotenberg-host:3000"
HEARTBEAT_URL="https://vigilmon.online/heartbeat/YOUR_TOKEN"

# POST an HTML snippet to the Chromium HTML conversion route
RESPONSE=$(curl -s -o /tmp/gotenberg_test.pdf -w "%{http_code}" \
  -F "files=@/dev/stdin;filename=test.html;type=text/html" \
  "${GOTENBERG_URL}/forms/chromium/convert/html" <<'EOF'
<!DOCTYPE html><html><body><h1>Gotenberg health check</h1></body></html>
EOF
)

HTTP_STATUS="$RESPONSE"

# Verify the response was HTTP 200 and produced a non-empty PDF
if [ "$HTTP_STATUS" = "200" ] && [ -s /tmp/gotenberg_test.pdf ]; then
  curl -s "${HEARTBEAT_URL}"
else
  echo "Gotenberg conversion failed: HTTP ${HTTP_STATUS}" >&2
  exit 1
fi

rm -f /tmp/gotenberg_test.pdf

Add this to cron:

0 * * * * /usr/local/bin/gotenberg_health_check.sh

If Chromium crashes between runs, the next hourly test fails (non-200 response or 0-byte PDF), the heartbeat is not sent, and Vigilmon alerts after the 65-minute window expires. This is the only monitoring path that catches the Chromium crash scenario the built-in /health endpoint cannot detect.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add Slack, email, or a webhook endpoint.
2. Set Consecutive failures before alert to 2 on the API health monitor — transient network glitches can cause single-probe failures.
3. Set Consecutive failures before alert to 1 on the conversion pipeline monitors — a single failure here means real PDF generation is broken.

Summary

| Monitor | Target | What It Catches | |---|---|---| | API health | GET /health | Container down, HTTP server crash | | Chromium pipeline | POST /forms/chromium/convert/url | Chromium crash, rendering failure | | LibreOffice pipeline | POST /forms/libreoffice/convert | LibreOffice process failure | | SSL certificate | Ingress HTTPS URL | Certificate expiry before PDFs break | | Cron heartbeat | Hourly conversion test | Silent Chromium crash /health misses |

Gotenberg's stateless design is one of its greatest strengths — but that statelessness means there's no persistent health state to query. Every monitoring signal must come from actively exercising the conversion pipeline. With Vigilmon watching the API endpoint, actively testing Chromium and LibreOffice routes, guarding SSL certificates, and running hourly heartbeat conversion tests, you get full-spectrum visibility into a service that is otherwise entirely opaque from the outside.