A Guide to Gotenberg
Gotenberg is a great open source project for converting files to PDF.
Starting Up Gotenberg
1 | docker run --rm -p 3000:3000 gotenberg/gotenberg:7 |
1 | # Run container in background |
View console output of Gotenberg
1 | docker container ls |
API Usage
Health Check
1 | http://localhost:3000/health |
Chromium
The Chromium module interacts with the Chromium browser to convert HTML documents to PDF.
Converting HTML URLs to PDF
1 | curl \ |
Converting local HTML files to PDF
1 | curl \ |
LibreOffice
The LibreOffice module interacts with LibreOffice to convert documents to PDF.
To convert documents to PDF
Files with the following extensions:
1 | .bib` `.doc` `.xml` `.docx` `.fodt` `.html` `.ltx` `.txt` `.odt` `.ott` `.pdb` `.pdf` `.psw` `.rtf` `.sdw` `.stw` `.sxw` `.uot` `.vor` `.wps` `.epub` `.png` `.bmp` `.emf` `.eps` `.fodg` `.gif` `.jpg` `.met` `.odd` `.otg` `.pbm` `.pct` `.pgm` `.ppm` `.ras` `.std` `.svg` `.svm` `.swf` `.sxd` `.sxw` `.tiff` `.xhtml` `.xpm` `.fodp` `.potm` `.pot` `.pptx` `.pps` `.ppt` `.pwp` `.sda` `.sdd` `.sti` `.sxi` `.uop` `.wmf` `.csv` `.dbf` `.dif` `.fods` `.ods` `.ots` `.pxl` `.sdc` `.slk` `.stc` `.sxc` `.uos` `.xls` `.xlt` `.xlsx` `.tif` `.jpeg` `.odp |
Converting local document files to PDF
Relative file path
1 | curl \ |
Absolute file path
1 | curl \ |
Multiple files
1 | curl \ |
Request by Java OkHttp
1 | private static final String GOTENBERG_SERVICE_HOST = "http://xxx.xxx.xxx.xxx:3000"; |
PDF Engines
Merge multiple PDF files to one PDF file.
1 | curl \ |
Webhook
The Webhook module provides a middleware that allows you to upload the output file from multipart/form-data
routes to the destination of your choice.
1 | curl \ |
The middleware reads the following headers:
Gotenberg-Webhook-Url
- the callback to use - requiredGotenberg-Webhook-Error-Url
- the callback to use if error - requiredGotenberg-Webhook-Method
- the HTTP method to use (POST, PATCH, or PUT - default POST).Gotenberg-Webhook-Error-Method
- the HTTP method to use if error (POST, PATCH, or PUT - default POST).Gotenberg-Webhook-Extra-Http-Headers
- the extra HTTP headers to send to both URLs (JSON format).
Common Errors
Error: file name is too long
1 | {"level":"error","ts":1649232587.172472,"logger":"api","msg":"create request context: copy to disk: create local file: open /tmp/9e10e36d-c5a9-4623-9fac-92db4a0d0982/xxx.doc: file name too long","trace":"de0b5ce2-5a99-406e-a61d-4abb65ef0294","remote_ip":"xxx.xxx.xxx.xxx","host":"xxx.xxx.xxx.xxx:3000","uri":"/forms/libreoffice/convert","method":"POST","path":"/forms/libreoffice/convert","referer":"","user_agent":"okhttp/4.9.3","status":500,"latency":13161094736,"latency_human":"13.161094736s","bytes_in":6983097,"bytes_out":21} |
Solutions
Decreasing your file name length.
Error: file name contains UTF-8 characters
1 | {"level":"error","ts":1649234692.9638329,"logger":"api","msg":"convert to PDF: unoconv PDF: unix process error: wait for unix process: exit status 6","trace":"28d9a196-10e5-4c7d-af6a-178494f49cd1","remote_ip":"xxx.xxx.xxx.xxx","host":"xxx.xxx.xxx.xxx:3000","uri":"/forms/libreoffice/convert","method":"POST","path":"/forms/libreoffice/convert","referer":"","user_agent":"okhttp/4.9.3","status":500,"latency":130617774,"latency_human":"130.617774ms","bytes_in":11559,"bytes_out":21} |
Solutions
Encoding filename by URLEncoder.encode(fileName, "UTF-8")
.
Error: file extension name is not right
1 | {"level":"error","ts":1649234777.9096093,"logger":"api","msg":"validate form data: no form file found for extensions: [.bib .doc .xml .docx .fodt .html .ltx .txt .odt .ott .pdb .pdf .psw .rtf .sdw .stw .sxw .uot .vor .wps .epub .png .bmp .emf .eps .fodg .gif .jpg .jpeg .met .odd .otg .pbm .pct .pgm .ppm .ras .std .svg .svm .swf .sxd .sxw .tif .tiff .xhtml .xpm .odp .fodp .potm .pot .pptx .pps .ppt .pwp .sda .sdd .sti .sxi .uop .wmf .csv .dbf .dif .fods .ods .ots .pxl .sdc .slk .stc .sxc .uos .xls .xlt .xlsx]","trace":"10e6ffd8-2d00-4374-b6fb-0c4ff6af3043","remote_ip":"xxx.xxx.xxx.xxx","host":"xxx.xxx.xxx.xxx:3000","uri":"/forms/libreoffice/convert","method":"POST","path":"/forms/libreoffice/convert","referer":"","user_agent":"okhttp/4.9.3","status":400,"latency":3885166,"latency_human":"3.885166ms","bytes_in":11551,"bytes_out":449} |
Solutions
Files in form data should have a correct file extension.