Skip to content

Commit

Permalink
feat: update documentation for last 7.x version
Browse files Browse the repository at this point in the history
  • Loading branch information
@gulien
gulien committed Nov 20, 2023
1 parent 12f9b7d commit 878242e
Show file tree
Hide file tree
Showing 6 changed files with 129 additions and 125 deletions.
103 changes: 39 additions & 64 deletions docs/configuration.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -25,38 +25,33 @@ The following flags allow you to configure the API module:

The Chromium module interacts with the Chromium browser to convert HTML documents to PDF.

The following flags allow you to configure the Chromium module:

| Flag | Description | Default |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ------------------- |
| <span class="badge badge--secondary">--chromium-allow-file-access-from-files</span> | Allow file:// URIs to read other file:// URIs. | false |
| <span class="badge badge--secondary">--chromium-allow-insecure-localhost</span> | Ignore TLS/SSL errors on localhost. | false |
| <span class="badge badge--secondary">--chromium-allow-list</span> | Set the allowed URLs for Chromium using a regular expression. | All |
| <span class="badge badge--secondary">--chromium-deny-list</span> | Set the denied URLs for Chromium using a regular expression. | `^file:///[^tmp].*` |
| <span class="badge badge--secondary">--chromium-ignore-certificate-errors</span> | Ignore the certificate errors. | false |
| <span class="badge badge--secondary">--chromium-disable-web-security</span> | Don't enforce the same-origin policy. | false |
| <span class="badge badge--secondary">--chromium-incognito</span> | Start Chromium with incognito mode. | false |
| <span class="badge badge--secondary">--chromium-failed-starts-threshold</span> | Set the number of consecutive failed starts after which the module is considered unhealthy. | 5 |
| <span class="badge badge--secondary">--chromium-host-resolver-rules</span> | Set custom mappings to the host resolver. | None |
| <span class="badge badge--secondary">--chromium-proxy-server</span> | Set the outbound proxy server; this switch only affects HTTP and HTTPS requests. | None |
| <span class="badge badge--secondary">--chromium-disable-javascript</span> | Disable JavaScript. | false |
| <span class="badge badge--secondary">--chromium-disable-routes</span> | Disable the routes. | false |

:::info

It starts a dedicated Chromium instance for each conversion.

:::
By default, a long-running Chromium browser handles the conversions. This stateful mode allows for faster unitary
conversion, but there is a lock mechanism as a Chromium browser cannot perform parallel operations.

:::info
In other words, under heavy load, you should consider scaling up your number of Gotenberg instances.

If `--chromium-failed-starts-threshold=0`, there is no health check for this module.
The following flags allow you to configure the Chromium module:

:::
| Flag | Description | Default |
| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------- |
| <span class="badge badge--secondary">--chromium-restart-after</span> | Number of conversions after which Chromium will automatically restart. Set to 0 to disable this feature. | 0 |
| <span class="badge badge--secondary">--chromium-auto-start</span> | Automatically launch Chromium upon initialization if set to true; otherwise, Chromium will start at the time of the first conversion. | false |
| <span class="badge badge--secondary">--chromium-start-timeout</span> | Maximum duration to wait for Chromium to start or restart. | 10s |
| <span class="badge badge--secondary">--chromium-allow-file-access-from-files</span> | Allow file:// URIs to read other file:// URIs. | false |
| <span class="badge badge--secondary">--chromium-allow-insecure-localhost</span> | Ignore TLS/SSL errors on localhost. | false |
| <span class="badge badge--secondary">--chromium-allow-list</span> | Set the allowed URLs for Chromium using a regular expression. | All |
| <span class="badge badge--secondary">--chromium-deny-list</span> | Set the denied URLs for Chromium using a regular expression. | `^file:///[^tmp].*` |
| <span class="badge badge--secondary">--chromium-ignore-certificate-errors</span> | Ignore the certificate errors. | false |
| <span class="badge badge--secondary">--chromium-disable-web-security</span> | Don't enforce the same-origin policy. | false |
| <span class="badge badge--secondary">--chromium-incognito</span> | Start Chromium with incognito mode. | false |
| <span class="badge badge--secondary">--chromium-host-resolver-rules</span> | Set custom mappings to the host resolver. | None |
| <span class="badge badge--secondary">--chromium-proxy-server</span> | Set the outbound proxy server; this switch only affects HTTP and HTTPS requests. | None |
| <span class="badge badge--secondary">--chromium-disable-javascript</span> | Disable JavaScript. | false |
| <span class="badge badge--secondary">--chromium-disable-routes</span> | Disable the routes. | false |

:::caution

The `amd64` Docker image uses Google Chrome stable, while other architectures use an earlier version of Chromium.
The `amd64` Docker image uses Google Chrome stable, while other architectures use Chromium.

:::

Expand All @@ -65,39 +60,19 @@ The `amd64` Docker image uses Google Chrome stable, while other architectures us
The LibreOffice module interacts with [LibreOffice](https://www.libreoffice.org/) to convert numerous documents to PDF,
thanks to [unoconv](https://github.com/unoconv/unoconv).

The following flags allow you to configure the LibreOffice module:

| Flag | Description | Default |
| ---------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------- |
| <span class="badge badge--secondary">--libreoffice-disable-routes</span> | Disable the route. | false |
| <span class="badge badge--secondary">--uno-listener-start-timeout</span> | Time limit for starting the LibreOffice listener. | 10s |
| <span class="badge badge--secondary">--uno-listener-restart-threshold</span> | Conversions limit after which the LibreOffice listener is restarted. | 10 |

### Stateful or Stateless

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.
By default, a long-running LibreOffice instance handles the conversions. This stateful mode allows for faster unitary
conversion, but there is a lock mechanism as a single LibreOffice instance 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).
In other words, under heavy load, you should consider scaling up your number of Gotenberg instances

:::info

Gotenberg restarts the long-running LibreOffice listener if it is unhealthy before and after a conversion.

:::

:::info

If `--uno-listener-restart-threshold=0` (i.e., stateless mode), there is no health check for this module.

:::

:::caution

The `--uno-*` properties also impact the performance of the UNO PDF engine (see [PDF Engines](#pdf-engines)).
The following flags allow you to configure the LibreOffice module:

:::
| Flag | Description | Default |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| <span class="badge badge--secondary">--libreoffice-restart-after</span> | Number of conversions after which LibreOffice will automatically restart. Set to 0 to disable this feature. | 10 |
| <span class="badge badge--secondary">--libreoffice-auto-start</span> | Automatically launch LibreOffice upon initialization if set to true; otherwise, LibreOffice will start at the time of the first conversion. | false |
| <span class="badge badge--secondary">--libreoffice-start-timeout</span> | Maximum duration to wait for LibreOffice to start or restart. | 10s |
| <span class="badge badge--secondary">--libreoffice-disable-routes</span> | Disable the route. | false |

### Switch Language

Expand All @@ -112,7 +87,7 @@ 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 &&\
DEBIAN_FRONTEND=noninteractive apt-get install -y -qq --no-install-recommends -t bookworm-backports libreoffice-l10n-de &&\
sed -i '/de_DE.UTF-8/s/^# //g' /etc/locale.gen &&\
locale-gen &&\
# Cleanup.
Expand All @@ -136,12 +111,12 @@ PDF files.

Currently, Gotenberg supports the following PDF engines:

| Engine | Merge | Convert into PDF/A | Name |
| -------------------------------------------- |------ | ------------------ | ------------- |
| [PDFtk](https://gitlab.com/pdftk-java/pdftk) | ✅ | ❌ | pdtk |
| [PDFcpu](https://github.com/pdfcpu/pdfcpu) | ✅ | ❌ | pdcpu |
| [QPDF](https://github.com/qpdf/qpdf) | ✅ | ❌ | qpdf |
| [UNO](https://github.com/unoconv/unoconv) | ❌ | ✅ | uno-pdfengine |
| Engine | Merge | Convert into PDF/A | Name |
| -------------------------------------------- |------ | ------------------ | --------------------- |
| [PDFtk](https://gitlab.com/pdftk-java/pdftk) | ✅ | ❌ | pdtk |
| [PDFcpu](https://github.com/pdfcpu/pdfcpu) | ✅ | ❌ | pdcpu |
| [QPDF](https://github.com/qpdf/qpdf) | ✅ | ❌ | qpdf |
| [UNO](https://github.com/unoconv/unoconv) | ❌ | ✅ | libreoffice-pdfengine |

The following flags allow you to configure the PDF Engines module:

Expand All @@ -152,7 +127,7 @@ The following flags allow you to configure the PDF Engines module:

:::info

For instance, the value *"pdftk,uno-pdfengine"* selects PDFtk as the first engine, and UNO as the second.
For instance, the value *"pdftk,libreoffice-pdfengine"* selects PDFtk as the first engine, and UNO as the second.

:::

Expand Down
19 changes: 19 additions & 0 deletions docs/getting-started/clients.mdx
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
---
id: clients
title: Clients
---

Most routes within Gotenberg are designed to accept *multipart/form-data* requests.

**There's no need for a custom client to create these requests, as the majority of programming languages and tools,
including cURL, offer native support.**

However, due to popular demand, both we and our community have developed a range of clients for ease of use:

* Our *official* PHP client for Gotenberg is available in the [gotenberg/gotenberg-php](https://github.com/gotenberg/gotenberg-php) package.
* A collection of community-created clients can be found on the [Awesome list](https://github.com/gotenberg/awesome-gotenberg#clients).

In the upcoming [routes](/docs/routes) guide, we'll explore how to utilize the different routes offered by Gotenberg.

While we will provide basic cURL examples, remember that there are numerous methods to create *multipart/form-data* requests,
such as using streams or specifying file locations directly for form files.
6 changes: 3 additions & 3 deletions docs/getting-started/installation.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,6 @@ id: installation
title: Installation
---

<script async type="text/javascript" src="//cdn.carbonads.com/carbon.js?serve=CWYI4KQL&placement=gotenbergdev" id="_carbonads_js"></script>

This guide is not intended to provide a comprehensive tour of Docker and its orchestrators. Rather, it's designed to
be concise enough to assist beginners in getting started while helping power users sidestep potential pitfalls.

Expand Down Expand Up @@ -145,6 +143,7 @@ There are a few limitations to be aware of:

1. Consider using HTTP/2 to bypass the [32MB request size limit](https://cloud.google.com/run/quotas?hl=en).
2. Consider disabling the [webhook feature](/docs/configuration#webhook) as it does not work on Cloud Run.
3. Consider enabling auto-start for [Chromium](/docs/configuration#chromium) and/or [LibreOffice](/docs/configuration#libreoffice).

## Modules Configuration

Expand Down Expand Up @@ -183,4 +182,5 @@ Do not redefine the Gotenberg Docker image default entrypoint, but override the

## What's next?

Now that you have Gotenberg up and running, you can start using it. Read the [routes guide](/docs/routes) to learn more.
Now that you have Gotenberg up and running, you can start using it. Install a custom [client](clients) or
read the [routes guide](/docs/routes) to learn more.
Loading

0 comments on commit 878242e

Please sign in to comment.