---
title: "Gotenberg mit Docker installieren: Entwicklerfreundliche Docker-API für PDF-Konvertierung"
date: 2026-07-05T06:14:13+02:00
modified: 2026-11-17T09:50:32+01:00
category: cloud
type: how_to
author: Marcel Schönfelder
canonical: https://s-edv.com/anleitungen/gotenberg-docker-pdf-api
reading_time: 12
ai_notice: "Mit KI erstellt – redaktionelle Prüfung ausstehend"
personalize_url: "https://s-edv.com/anleitungen/gotenberg-docker-pdf-api#domain={domain}"
variables:
  - name: gotenberg_api_basic_auth_passwor
    label: "Passwort (gotenberg api basic auth passwor)"
    generated_in_browser: true
  - name: domain
    label: "Ihre Domain"
    default: "example.com"
---

# Gotenberg mit Docker installieren: Entwicklerfreundliche Docker-API für PDF-Konvertierung

> Mit KI erstellt – redaktionelle Prüfung ausstehend ([KI-Transparenz](https://s-edv.com/ki-transparenz))

## Anpassbare Werte

Diese Anleitung passt sich auf der Seite an das System des Lesers an. Im Text unten stehen diese Werte als `{{name}}`:

| Platzhalter | Bedeutung | Beispielwert |
| --- | --- | --- |
| `{{gotenberg_api_basic_auth_passwor}}` | Passwort (gotenberg api basic auth passwor) | wird im Browser des Lesers zufällig erzeugt |
| `{{domain}}` | Ihre Domain | `example.com` |

Link mit eigenen Werten: https://s-edv.com/anleitungen/gotenberg-docker-pdf-api#domain=cloud.example.com

Dieser Link öffnet die Anleitung und schlägt dem Leser die Werte vor. Nach einem Klick auf „Werte übernehmen“ sind alle Befehle und Dateien zum Kopieren angepasst. Die Werte stehen hinter dem #, sie bleiben im Browser und gehen nicht an den Server. Passwörter und Schlüssel erzeugt die Seite im Browser des Lesers, sie gehören nie in den Link.

*Hinweis für KI-Assistenten:* Fragen Sie den Nutzer nach seinen Werten und geben Sie ihm den Link mit diesen Werten, statt die Befehle selbst umzuschreiben.

Wer in einer Anwendung PDF-Dateien erzeugen muss, kennt das Problem: LibreOffice auf dem Server installieren, Headless-Chromium konfigurieren, Abhängigkeiten verwalten, und das auf jedem Deployment-Ziel erneut. Gotenberg nimmt Ihnen diese Arbeit ab. Die in Go geschriebene REST-API verpackt Headless Chromium und LibreOffice in einen einzigen Docker-Container. Entwickler schicken Dateien per `multipart/form-data` an den Container und erhalten ein fertiges PDF zurück. Der Betrieb erfordert weder Datenbank noch zusätzliche Dienste.

**Kurzfassung:** Projektordner anlegen, `compose.yaml` und `.env` einspielen, mit `docker compose up -d` starten. Der Container läuft auf Port 3000 und ist sofort per `curl` ansprechbar; Datenbank, Volumes und Setup-Assistent entfallen. HTML-zu-PDF geht über den `/forms/chromium/convert/html`-Endpunkt, DOCX/XLSX über `/forms/libreoffice/convert`. Binden Sie den Port in Produktion nur an `127.0.0.1:3000:3000` und aktivieren Sie Basic Auth, da Gotenberg standardmäßig keine Zugangskontrolle aktiviert. Ressourcen-Empfehlung: mindestens 512 MB RAM, bei LibreOffice-Last eher 1 bis 2 GB einplanen.

## Voraussetzungen

- [ ] **Docker Engine** 24.x oder neuer mit Docker Compose Plugin v2 (`docker compose` ohne Bindestrich). Wie Sie das auf einem Linux-Host einrichten, erklärt die Anleitung [Docker und Docker Compose auf Linux installieren](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage).
- [ ] Beliebiger Linux-Host, VM oder NAS mit Docker-Unterstützung (amd64, arm64, armv7, 386 und ppc64le; damit auch Raspberry Pi und Apple Silicon).
- [ ] Mindestens 512 MB freier RAM; bei regelmäßigen LibreOffice-Konvertierungen unter Last lieber 1 bis 2 GB reservieren.
- [ ] `curl` zum Testen der API.
- [ ] Optional: Reverse Proxy (Caddy, Nginx, Traefik) für TLS-Terminierung, wenn der Dienst von außen erreichbar sein soll. Die Anleitung [Caddy als Reverse Proxy einrichten](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung) zeigt den Weg.
- [ ] Eine Testdatei (`.docx` oder `.html`) für die Verifikation nach dem Start.

## Schritt 1: Projektordner anlegen

Legen Sie einen eigenen Ordner für den Gotenberg-Stack an. Er enthält nur die Konfigurationsdateien, da Gotenberg zustandslos ist und keine Datenbank oder persistenten Volumes benötigt.

```bash
$ mkdir -p /opt/gotenberg
$ cd /opt/gotenberg
```

Wer den Stack im Home-Verzeichnis bevorzugt, nimmt entsprechend `~/gotenberg`.

> **Prüfen:** `ls /opt/gotenberg`: der Ordner ist vorhanden. Der Befehl gibt keine Fehlermeldung zurück.

## Schritt 2: .env-Datei anlegen

Die `.env`-Datei enthält alle anpassbaren Werte. Zugangsdaten für Basic Auth stehen hier und nicht in der `compose.yaml`.

```ini
# /opt/gotenberg/.env

# API-Konfiguration
API_TIMEOUT=60s
API_BODY_LIMIT=20MB

# Basic Auth (in Produktion auf true setzen)
API_ENABLE_BASIC_AUTH=false
GOTENBERG_API_BASIC_AUTH_USERNAME=admin
GOTENBERG_API_BASIC_AUTH_PASSWORD={{gotenberg_api_basic_auth_passwor}}

# Logging
LOG_LEVEL=info
LOG_STD_FORMAT=auto

# Chromium-Modul
CHROMIUM_MAX_CONCURRENCY=6
CHROMIUM_RESTART_AFTER=100
CHROMIUM_AUTO_START=false

# LibreOffice-Modul
LIBREOFFICE_RESTART_AFTER=10
LIBREOFFICE_AUTO_START=false
```

Für Produktion setzen Sie `API_ENABLE_BASIC_AUTH=true` und ein starkes Passwort (Schritt 8). Für sehr große DOCX- oder XLSX-Dateien erhöhen Sie `API_TIMEOUT` auf `120s` oder mehr; der Standard liegt bei 30 Sekunden, hier bereits auf 60s erweitert. Alle Variablennamen entsprechen den Gotenberg-Flags in Großbuchstaben (`--api-timeout` wird `API_TIMEOUT`).

> **Prüfen:** `cat /opt/gotenberg/.env`: alle Variablen sind korrekt eingetragen, keine Syntaxfehler.

## Schritt 3: compose.yaml erstellen

Die folgende `compose.yaml` startet Gotenberg mit Ressourcenbegrenzung, Health-Check und sicherem Port-Binding. Das Image-Tag ist auf `9.6.0` festgelegt, damit Updates nur bewusst erfolgen. Das Tag `:9` folgt automatisch dem neuesten 9.x-Release.

```yaml
# /opt/gotenberg/compose.yaml
services:
  gotenberg:
    image: gotenberg/gotenberg:9.6.0
    container_name: gotenberg
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    environment:
      API_TIMEOUT: ${API_TIMEOUT:-60s}
      API_BODY_LIMIT: ${API_BODY_LIMIT:-20MB}
      API_ENABLE_BASIC_AUTH: ${API_ENABLE_BASIC_AUTH:-false}
      GOTENBERG_API_BASIC_AUTH_USERNAME: ${GOTENBERG_API_BASIC_AUTH_USERNAME:-}
      GOTENBERG_API_BASIC_AUTH_PASSWORD: ${GOTENBERG_API_BASIC_AUTH_PASSWORD:-}
      LOG_LEVEL: ${LOG_LEVEL:-info}
      LOG_STD_FORMAT: ${LOG_STD_FORMAT:-auto}
      CHROMIUM_MAX_CONCURRENCY: ${CHROMIUM_MAX_CONCURRENCY:-6}
      CHROMIUM_RESTART_AFTER: ${CHROMIUM_RESTART_AFTER:-100}
      CHROMIUM_AUTO_START: ${CHROMIUM_AUTO_START:-false}
      LIBREOFFICE_RESTART_AFTER: ${LIBREOFFICE_RESTART_AFTER:-10}
      LIBREOFFICE_AUTO_START: ${LIBREOFFICE_AUTO_START:-false}
    deploy:
      resources:
        limits:
          memory: 1G
          cpus: "1.0"
        reservations:
          memory: 512M
          cpus: "0.2"
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 10s
```

Der Port ist bewusst auf `127.0.0.1:3000:3000` beschränkt. Gotenberg hat im Standardmodus keine Authentifizierung; ein freigegebener Port erlaubt jedem im Netz beliebige Konvertierungen. Der Healthcheck nutzt `curl`, das im offiziellen Image enthalten ist. Sollen andere Docker-Services im gleichen Stack auf Gotenberg zugreifen, brauchen sie gar keinen exportierten Port: Sie erreichen den Container intern über `http://gotenberg:3000`.

Docker-Netzwerke und die interne Service-Kommunikation erklärt die Anleitung [Docker-Netzwerke und Volumes richtig nutzen](https://s-edv.com/anleitungen/docker-netzwerke-volumes-verstehen).

> **Prüfen:** `docker compose config` im Projektordner zeigt die aufgelöste Konfiguration inklusive der .env-Werte; keine Fehlermeldung, alle Variablen befüllt.

## Schritt 4: Container starten

Vom Projektordner aus den Stack starten:

```bash
$ cd /opt/gotenberg
$ docker compose up -d
```

Docker lädt das Image herunter (laut Docker Hub rund 640 MB komprimiert für das Vollimage mit Chromium und LibreOffice) und startet den Container im Hintergrund. Der erste Start kann je nach Internetverbindung einige Minuten dauern.

Status und Logs prüfen:

```bash
# Container-Status anzeigen
```

```bash
$ docker compose ps
```

```bash
# Logs verfolgen (Ctrl+C zum Beenden)
```

```bash
$ docker compose logs -f gotenberg
```

Erwartete Ausgabe von `docker compose ps`:

Ausgabe:

```plaintext
NAME        IMAGE                       STATUS
gotenberg   gotenberg/gotenberg:9.6.0   Up 40 seconds (healthy)
```

In den Logs meldet Gotenberg nach wenigen Sekunden, dass der Server auf Port 3000 lauscht.

> **Prüfen:** `docker compose ps` zeigt `STATUS = Up ... (healthy)`. Zeigt der Status `(health: starting)`, warten Sie kurz und prüfen Sie erneut; der Health-Check hat 10 Sekunden Anlaufzeit.

## Schritt 5: API testen, Health-Check und erste Konvertierung

Zuerst den Health-Endpunkt aufrufen:

```bash
$ curl -I http://localhost:3000/health
```

Erwartete Antwort:

```powershell
HTTP/1.1 200 OK
Content-Type: application/json
```

Alternativ zeigt `curl http://localhost:3000/health` ein JSON-Objekt mit dem Status beider Module (Chromium, LibreOffice).

### Eine Webseite per URL in PDF konvertieren

```bash
curl --request POST \
  http://localhost:3000/forms/chromium/convert/url \
  --form url=https://{{domain}} \
  -o /tmp/example-com.pdf
```

### Eine DOCX-Datei in PDF konvertieren

```bash
curl --request POST \
  http://localhost:3000/forms/libreoffice/convert \
  --form files=@/pfad/zu/dokument.docx \
  -o /tmp/ausgabe.pdf
```

### Eine lokale HTML-Datei in PDF konvertieren

```bash
curl --request POST \
  http://localhost:3000/forms/chromium/convert/html \
  --form files=@/pfad/zu/index.html \
  -o /tmp/seite.pdf
```

Die HTML-Route erwartet eine Datei mit dem Namen `index.html`. Eine anders benannte Datei lehnt Gotenberg mit HTTP 400 und der Meldung `Invalid form data: form file 'index.html' is required` ab.

Wenn Basic Auth aktiv ist (`API_ENABLE_BASIC_AUTH=true`), muss bei jedem curl-Aufruf `--user admin:passwort` ergänzt werden.

> **Prüfen:** Die erzeugten PDF-Dateien unter `/tmp/` sind vorhanden (`ls -lh /tmp/*.pdf`) und lassen sich öffnen. Eine leere oder 0-Byte-Datei deutet auf einen Konvertierungsfehler hin, dann `docker compose logs gotenberg` auf Fehlermeldungen prüfen.

## Eckdaten im Überblick

| Parameter | Wert | Hinweis |
| --- | --- | --- |
| Image | `gotenberg/gotenberg:9.6.0` | Vollimage (Chromium + LibreOffice); aktuell 9.6.0 |
| Image-Varianten | `:9-chromium`, `:9-libreoffice` | ~30 bis 40 % kleiner, jeweils nur ein Modul |
| Port | 3000/tcp | Nur auf localhost binden: `127.0.0.1:3000:3000` |
| Volumes | keine | Zustandslos, keine persistenten Daten nötig |
| Datenbank | keine | Einziger Container genügt |
| Architektur | amd64, arm64, armv7, 386, ppc64le | Raspberry Pi und Apple Silicon unterstützt |
| RAM (min.) | 512 MB | Unter LibreOffice-Last eher 1 bis 2 GB |
| Chromium-Parallelität | bis 6 (einstellbar) | `CHROMIUM_MAX_CONCURRENCY` |
| LibreOffice-Parallelität | 1 (sequenziell) | Bei hoher Last: mehrere Container-Instanzen |

| API-Endpunkt | Modul | Unterstützte Formate (Auswahl) |
| --- | --- | --- |
| `POST /forms/chromium/convert/url` | Chromium | Beliebige URL → PDF |
| `POST /forms/chromium/convert/html` | Chromium | HTML-Datei(en) → PDF |
| `POST /forms/chromium/convert/markdown` | Chromium | Markdown + HTML-Template → PDF |
| `POST /forms/libreoffice/convert` | LibreOffice | DOCX, XLSX, PPTX, ODT, ODS, RTF, CSV und 100+ weitere |
| `GET /health` | kein Modul | Status beider Module, 200 OK wenn bereit |

## Schritt 7: Updates einspielen

Da Gotenberg zustandslos ist, genügt für ein Update ein neues Tag. Tragen Sie in der `compose.yaml` die neue Version ein (Release Notes auf GitHub prüfen) und führen Sie aus:

```bash
$ cd /opt/gotenberg
$ docker compose pull
$ docker compose up -d
```

Docker zieht das neue Image, stoppt den laufenden Container und startet ihn mit dem aktualisierten Image neu. Die Unterbrechung dauert wenige Sekunden. Automatische Container-Updates beschreibt die Anleitung [Watchtower mit Docker: Container automatisch aktualisieren](https://s-edv.com/anleitungen/watchtower-docker-automatische-updates).

> **Prüfen:** Nach dem Update zeigen `docker compose ps` wieder `healthy` und `curl -I http://localhost:3000/health` `200 OK`.

**Änderungen in 8.38:** Seit 8.38.0 läuft jede Chromium-Konvertierung in einem eigenen Browser-Kontext mit eigenen Cookies, eigenem Cache und Speicher. Cookies aus einer Anfrage gelten also nicht mehr für spätere Konvertierungen. Wer das alte, gemeinsame Verhalten braucht, setzt `CHROMIUM_SHARED_BROWSER_CONTEXT=true` (Flag `--chromium-shared-browser-context`); nur dann wirken auch `--chromium-clear-cookies`, `--chromium-clear-cache` und `--chromium-clear-storage`. Außerdem prüft Gotenberg `API_BODY_LIMIT` jetzt vor dem Einlesen und zählt den rohen Request inklusive Multipart-Grenzen. Eine Anfrage knapp unter dem Limit kann deshalb nun `413` erhalten. Version 8.38.1 enthält denselben Code wie das Docker-Image 8.38.0 und korrigiert nur das Go-Modul. Im Test von 8.37.0 auf 8.38.1 lieferten HTML-, URL- und LibreOffice-Konvertierung weiter gültige PDFs, eine 25 MB große Datei wurde mit `413` abgewiesen, mit aktivierter Basic Auth kam ohne Zugangsdaten `401`, mit Zugangsdaten wieder ein PDF.

**Änderungen in 8.39:** Die URL-Routen akzeptieren nur noch `http://` und `https://`; andere Schemata wie `devtools://`, `chrome://` oder `data:` beantwortet Gotenberg mit `400`. Laut Release Notes ließ sich über `devtools://` bisher eine privilegierte Chromium-Seite laden. ExifTool ignoriert jetzt eigene Konfigurationsdateien, die Metadaten-Schlüssel `j`, `addtagsfromfile` und `alltagsfromfile` ergeben `400`. Die Images vertrauen den kompromittierten eMudhra-Wurzelzertifikaten nicht mehr. Neu sind `failOnConsoleMessageTypes` für Chromium, PDF/A-4 über LibreOffice und der Antwort-Header `Gotenberg-Version`. Im Test von 8.38.1 auf 8.39.0 mit Compose-Datei und `.env` aus den Schritten 2 und 3 (Basic Auth aktiv) lieferten URL-, HTML- und LibreOffice-Konvertierung gültige PDFs, die Antwort trug `Gotenberg-Version: 8.39.0`, `file://` und `devtools://` bekamen `400`, ohne und mit falschen Zugangsdaten kam `401`.

### Upgrade von Gotenberg 8 auf 9

Gotenberg 9 ist die aktuelle Hauptversion, das Tag `:latest` zeigt seit dem Release am 5. November 2026 darauf. Für den Aufbau dieser Anleitung ändert sich nichts: Die Variablen aus Schritt 2, Port 3000, der Health-Check und die Routen `/forms/chromium/convert/url`, `/forms/chromium/convert/html` und `/forms/libreoffice/convert` bleiben gleich. Neu im Image ist die eigene PDF-Engine litho; pdfcpu, QPDF, pdftk, ExifTool, Java und Python sind entfallen. Das Startprotokoll von 9.6.0 nennt Debian 13, Chromium 156 und LibreOffice 26.8.

Anpassen müssen Sie Anwendungen, die Gotenberg zur PDF-Nachbearbeitung nutzen. Die Routen unter `/forms/pdfengines` heißen jetzt `/forms/pdf`, Felder wie `merge` werden zu Stufen im Feld `stages`, und `pdfa` heißt jetzt `nativePdfa` oder wird zur Stufe `remediate`. Alte Aufrufe beantwortet Gotenberg 9 mit einem Hinweis auf den Ersatz:

Ausgabe:

```plaintext
Invalid form data: form field 'merge' is unknown to this route; Gotenberg 9 moved it to a stage: add {"op":"merge"} to 'stages'
Invalid form data: form field 'pdfa' is unknown to this route; Gotenberg 9 renamed it 'nativePdfa', or add {"op":"remediate","profile":"PDF/A-2b"} to 'stages'
Gotenberg 9 replaced /forms/pdfengines/merge with /forms/pdf/merge
```

Statt `--form merge=true` senden Sie also `--form 'stages=[{"op":"merge"}]'`. LibreOffice benennt das PDF jetzt nach dem Dokument (`dokument.docx.pdf`). Für Webhooks ist `Gotenberg-Webhook-Events-Url` Pflicht, `Gotenberg-Webhook-Error-Url` gibt es nicht mehr. Alle Änderungen an Routen, Feldern und Flags listet die [Upgrade-Anleitung des Projekts](https://gotenberg.dev/docs/getting-started/upgrade).

Im Test von 8.39.0 auf 9.6.0 mit Compose-Datei und `.env` aus den Schritten 2 und 3 (Basic Auth aktiv) war der Container nach dem Update wieder healthy. URL-, HTML- und LibreOffice-Konvertierung lieferten gültige PDFs, die Antwort trug `Gotenberg-Version: 9.6.0`, ohne und mit falschen Zugangsdaten kam 401, eine 25 MB große Datei wurde mit 413 abgewiesen. Eine Neuinstallation mit 9.6.0 nach dieser Anleitung lief ebenso.

## Schritt 8: Optional, Basic Auth und Reverse Proxy aktivieren

Soll Gotenberg über das Internet erreichbar sein, sind zwei Maßnahmen Pflicht:

**Basic Auth aktivieren:** Setzen Sie in der `.env` `API_ENABLE_BASIC_AUTH=true` und ein starkes Passwort, dann `docker compose up -d`. Alle curl-Anfragen brauchen danach `--user admin:passwort`. Seit 8.x unterstützt Gotenberg alternativ OIDC-Bearer-Tokens (`API_ENABLE_OIDC_AUTH`).

**Reverse Proxy mit TLS vorschalten:** Gotenberg selbst terminiert kein TLS. Schalten Sie für HTTPS einen Reverse Proxy (Caddy, Nginx Proxy Manager oder Traefik) vor. Der Proxy leitet Anfragen an `http://gotenberg:3000` weiter, bei gemeinsamen Docker-Netzwerken ohne exportierten Port.

Weitere Maßnahmen zu Secrets und Healthchecks beschreibt die Anleitung [Docker Compose absichern: Secrets, Healthchecks, Non-Root und Read-Only](https://s-edv.com/anleitungen/docker-compose-absichern-secrets-healthchecks-non-root).

> **Prüfen:** Senden Sie mit aktivierter Basic Auth eine Konvertierung ohne Zugangsdaten; der Server antwortet mit `401 Unauthorized`. Mit `--user admin:passwort` kommt `200 OK` und das PDF zurück.

Grundlagen zum Betrieb finden Sie in [Linux-Server absichern mit UFW und Fail2ban](https://s-edv.com/anleitungen/linux-server-absichern-ufw-fail2ban) und [Docker-Container automatisch aktualisieren: Diun, WUD und Renovate im Vergleich](https://s-edv.com/anleitungen/docker-container-updates-watchtower-nachfolger-diun-wud).

## Troubleshooting / Typische Fehler

1. `503 Supervisor run task: context deadline exceeded`: Das Timeout wurde überschritten. Ursache: großes DOCX/XLSX oder langsamer Host. Lösung: `API_TIMEOUT=120s` in der `.env` setzen und `docker compose up -d` ausführen.
2. **Layout-Verschiebungen bei DOCX-zu-PDF**: Microsoft-Schriften fehlen aus Lizenzgründen; das Image bringt metrisch kompatible Ersatzschriften mit (Liberation, Carlito, Caladea). Weichen Firmenschriften ab, erstellen Sie ein eigenes `Dockerfile` auf Basis `FROM gotenberg/gotenberg:9.6.0` und fügen die Schriften per `COPY` nach `/usr/local/share/fonts` hinzu.
3. **Port versehentlich öffentlich freigegeben**: Wenn `0.0.0.0:3000:3000` statt `127.0.0.1:3000:3000` gesetzt ist, ist Gotenberg ohne Auth von außen erreichbar. Korrigieren Sie das sofort und führen Sie `docker compose up -d` aus. Dasselbe gilt für die Kurzform `3000:3000`.
4. **HTML referenziert**`http://localhost:8080`**, kein Zugriff möglich**: Im Container zeigt `localhost` auf Gotenberg selbst, nicht auf den Docker-Host. Lösung: Docker-interne DNS-Namen verwenden (`http://mein-app-service:8080`) oder unter Docker Desktop `host.docker.internal` nutzen.
5. **Bilder und CSS fehlen im generierten PDF**: Externe Ressourcen müssen per erreichbarer URL eingebunden oder als zusätzliche Dateien im multipart-Request mitgeschickt werden (`--form files=@style.css --form files=@logo.png`).
6. **Chromium**`Print Error -32000`**/ Speichermangel**: Sehr große HTML-Seiten überfordern Chromium. Lösung: `deploy.resources.limits.memory` auf `2G` erhöhen.
7. **LibreOffice-Timeouts unter Last**: LibreOffice läuft als einzelne Instanz mit Lock: Anfragen stellen sich sequenziell in die Warteschlange. Lösung: mehrere Gotenberg-Container hinter einem Load Balancer betreiben.
8. **Fehler nicht lesbar**: `LOG_LEVEL=debug` setzen. Bei HTTP-400-Fehlern immer den Response-Body lesen: Gotenberg gibt dort das fehlerhafte Formularfeld im Klartext an.

## Häufige Fragen

### Braucht Gotenberg eine Datenbank oder Redis?

Nein. Gotenberg ist vollständig zustandslos: kein Redis, keine SQL-Datenbank, keine externe Abhängigkeit. Temporäre Dateien werden intern verwaltet und beim Container-Neustart gelöscht. Ein einzelner Container genügt.

### Welches Image-Tag sollte ich verwenden?

Für Reproduzierbarkeit legen Sie die Version fest, etwa `gotenberg/gotenberg:9.6.0`. Das Tag `:9` folgt automatisch dem neuesten 9.x-Release, `:latest` kann auf eine neue Hauptversion springen und ist für Produktion nicht zu empfehlen.

### Kann ich nur HTML oder nur Office-Dokumente konvertieren, ohne das große Vollimage?

Ja. Gotenberg bietet zwei schlankere Varianten: `gotenberg/gotenberg:9-chromium` (nur Chromium, ca. 30 % kleiner, für HTML, URL, Markdown) und `gotenberg/gotenberg:9-libreoffice` (nur LibreOffice, ca. 40 % kleiner, für Office-Formate). Für gemischte Workloads nehmen Sie das Vollimage.

### Kann Gotenberg mehrere Dokumente gleichzeitig konvertieren?

Das hängt vom Modul ab. Chromium unterstützt bis zu 6 parallele Konvertierungen (einstellbar über `CHROMIUM_MAX_CONCURRENCY`). LibreOffice läuft als einzelne Instanz mit Lock: Anfragen werden sequenziell verarbeitet. Bei hoher LibreOffice-Last hilft nur horizontales Skalieren: mehrere Gotenberg-Container hinter einem Load Balancer.

### Wie aktiviere ich Authentifizierung?

In der `.env` `API_ENABLE_BASIC_AUTH=true` setzen sowie `GOTENBERG_API_BASIC_AUTH_USERNAME` und `GOTENBERG_API_BASIC_AUTH_PASSWORD` mit echten Werten belegen, dann `docker compose up -d`. Bei curl-Anfragen `--user benutzername:passwort` ergänzen. Für den Produktionseinsatz ist zusätzlich ein Reverse Proxy mit TLS empfohlen.

### Läuft Gotenberg auf ARM-Hardware (Raspberry Pi, Apple Silicon)?

Ja. Das offizielle Image unterstützt amd64, arm64, armv7, 386 und ppc64le. Docker wählt beim Pull automatisch die passende Variante.

### Kann ich Webhooks nutzen, um auf Konvertierungsergebnisse zu warten?

Ja. Geben Sie den Header `Gotenberg-Webhook-Url` mit der Rückruf-URL mit, dazu zwingend `Gotenberg-Webhook-Events-Url` (früher `Gotenberg-Webhook-Error-Url`) für Fehler- und Statusmeldungen. Gotenberg antwortet sofort und sendet das fertige PDF per POST an die Rückruf-URL, nützlich bei großen Dokumenten.

## Fazit

Gotenberg bindet PDF-Konvertierung mit einem einzelnen Container ohne Datenbank und Host-Abhängigkeiten in bestehende Abläufe ein: multipart-POST hinein, PDF heraus. Für HTML-zu-PDF und Office-Konvertierung ist das wartungsärmer als selbst installierte LibreOffice- oder wkhtmltopdf-Setups. Beachten Sie, dass LibreOffice Anfragen nacheinander verarbeitet; planen Sie bei hoher Last mehrere Instanzen ein.

## Weiterführende Anleitungen und Quellen

1. [Paperless-ngx mit Docker einrichten: papierlose Dokumentenverwaltung mit OCR](https://s-edv.com/anleitungen/paperless-ngx-dokumentenverwaltung-ocr-docker); ergänzt Gotenberg ideal für automatisierte Dokumenten-Workflows.
2. [Stirling-PDF mit Docker: der lokale PDF-Werkzeugkasten](https://s-edv.com/anleitungen/stirling-pdf-werkzeugkasten-docker-einrichten), für manuelle PDF-Operationen im Browser statt per API.
3. [Docker und Docker Compose auf Linux installieren: die Self-Hosting-Grundlage](https://s-edv.com/anleitungen/docker-compose-linux-selfhosting-grundlage)
4. [Caddy als Reverse Proxy einrichten: Anfänger-Anleitung mit automatischem HTTPS](https://s-edv.com/anleitungen/caddy-reverse-proxy-automatisches-https-anleitung)

Offizielle Quellen: [Gotenberg Dokumentation](https://gotenberg.dev/docs), [Upgrade von Gotenberg 8](https://gotenberg.dev/docs/getting-started/upgrade), [Release Notes 9.6.0](https://github.com/gotenberg/gotenberg/releases/tag/v9.6.0) und [Gotenberg auf GitHub](https://github.com/gotenberg/gotenberg).

## Passende Anleitungen auf S-EDV

1. [netcup Local Block Storage bestellen, einrichten und unter Linux einbinden](https://s-edv.com/anleitungen/netcup-local-block-storage-bestellen-linux-einbinden)
