LibreOffice
The LibreOffice module interacts with LibreOffice to convert documents to PDF, thanks to unoconv.
Properties
--libreoffice-disable-routes bool Disable the routes
--uno-listener-start-timeout duration Time limit for starting the LibreOffice listener (default 10s)
--uno-listener-restart-threshold int Conversions limit after which the LibreOffice listener is restarted - 0 means no long-running LibreOffice listener (default 10)
By default, a long-running LibreOffice listener handles the conversions. This stateful mode allows for faster unitary conversion, but there is a lock mechanism as a single LibreOffice listener cannot perform parallel operations.
In other words, under heavy load, you should consider scaling up your number of Gotenberg instances or switch the LibreOffice
module to a stateless mode with --uno-listener-restart-threshold=0 (i.e., a dedicated LibreOffice listener per conversion).
Gotenberg restarts the long-running LibreOffice listener if it is unhealthy before and after a conversion.
The --uno-* properties also impact the performance of the UNO PDF engine.
The property --unoconv-disable-listener is deprecated in favor of --uno-listener-restart-threshold with 0 as value.
Route
POST /forms/libreoffice/convert
This route accepts multipart/form-data requests and files with the following 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
.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
.odg
.dotx
.xltx
For instance:
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
-o my.pdf
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'files=@"/path/to/file.xlsx"' \
-o my.zip
- Orientation
- Page Ranges
- PDF Format
- Merge
landscape bool Set the paper orientation to landscape (default false)
For instance:
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'landscape="true"' \
-o my.pdf
nativePageRanges string Page ranges to print, e.g., '1-4' - empty means all pages
For instance:
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'nativePageRanges="1-5"' \
-o my.pdf
The page ranges are applied to all files independently.
nativePdfFormat string Use unoconv to convert the resulting PDF to the given PDF format
pdfFormat string The PDF format of the resulting PDF
You cannot use both form fields.
:::
Prefer the nativePdfFormat form field, as it is faster than calling LibreOffice again with pdfFormat.
:::
nativePdfFormat
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'nativePdfFormat="PDF/A-1a"' \
-o my.pdf
The form field nativePdfA1aFormat is deprecated in favor of nativePdfFormat.
pdfFormat
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file.docx"' \
--form 'pdfFormat="PDF/A-1a"' \
-o my.pdf
After a LibreOffice conversion, the PDF engines will convert the resulting PDF to a specific format.
Check the available PDF formats:
merge bool Merge all PDF files into an individual PDF file
By default, if you send more than one file to convert, the route returns a ZIP archive of the resulting PDF files. However, you may prefer to merge all the PDF files into an individual PDF file.
For instance:
curl \
--request POST 'http://localhost:3000/forms/libreoffice/convert' \
--form 'files=@"/path/to/file1.docx"' \
--form 'files=@"/path/to/file2.docx"' \
--form 'merge="true"' \
-o my.pdf
Gotenberg merges the PDF files alphabetically.
Health Check
If --uno-listener-restart-threshold=0 (i.e., stateless mode), there is no health check.
In stateful mode, the health route returns a 503 Service Unvailable response if the long-running
LibreOffice listener is unhealthy.
Gotenberg considers a restarting long-running LibreOffice listener healthy.
Switch Language
By default, LibreOffice uses the English language when it converts documents to PDF. You may override this behavior by building your own Docker image.
For instance, with the German language:
FROM gotenberg/gotenberg:7
USER root
RUN apt-get update -qq &&\
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t bullseye-backports libreoffice-l10n-de &&\
sed -i '/de_DE.UTF-8/s/^# //g' /etc/locale.gen &&\
locale-gen &&\
# Cleanup.
# Note: the Debian image does automatically a clean after each install thanks to a hook.
# Therefore, there is no need for apt-get clean.
# See https://stackoverflow.com/a/24417119/3248473.
rm -rf /var/lib/apt/lists/* /tmp/* /var/tmp/*
ENV LANG de_DE.UTF-8
ENV LANGUAGE de_DE:de
ENV LC_ALL de_DE.UTF-8
USER gotenberg
Metrics
The LibreOffice module exposes the following metrics:
{namespace}_unoconv_active_instances_count- current number of active unoconv instances.{namespace}_libreoffice_listener_active_instances_count- current number of active LibreOffice listener instances.{namespace}_libreoffice_listener_queue_length- current number of processes in the LibreOffice listener queue.
The metrics unoconv_listener_active_instances_count and unoconv_listener_queue_length
are deprecated in favor of libreoffice_listener_active_instances_count and libreoffice_listener_queue_length.
See Prometheus for more details.
Troubleshooting
Filename contains non-Latin characters
convert to PDF: unoconv PDF: unix process error: wait for unix process: exit status 6
Make sure the filename is UTF-8 encoded. See issue #427 for more details.
Troublesome .pptx file
If you keep getting 500 Internal Server Error while trying to convert a .pptx file, a common workaround is to
increase the memory and CPU available to Gotenberg. See issue #465
for more details.