From 8287cf386b89476fccd74c36b92b89b0a9d5ca67 Mon Sep 17 00:00:00 2001 From: Julien Neuhart Date: Tue, 27 Aug 2019 11:00:26 +0200 Subject: [PATCH] improving documentation on timeout issues --- .../docs/content/03-environment-variables.md | 1 + build/docs/content/04-html.md | 7 ++++ build/docs/content/07-office.md | 11 +++-- build/docs/content/09-timeout.md | 1 + build/docs/content/13-ping.md | 7 +--- build/docs/content/14-fonts.md | 2 +- docs/index.html | 41 +++++++++++++------ 7 files changed, 48 insertions(+), 22 deletions(-) diff --git a/build/docs/content/03-environment-variables.md b/build/docs/content/03-environment-variables.md index 0aedc995..ff1f8289 100644 --- a/build/docs/content/03-environment-variables.md +++ b/build/docs/content/03-environment-variables.md @@ -42,6 +42,7 @@ You may also disable LibreOffice (unoconv) with `DISABLE_UNOCONV`. ## Default wait timeout By default, the API will wait 10 seconds before it considers the conversion to be unsuccessful. +If unsucessful, it returns a `504` HTTP code. You may customize this timeout thanks to the environment variable `DEFAULT_WAIT_TIMEOUT`. diff --git a/build/docs/content/04-html.md b/build/docs/content/04-html.md index 8f1e5070..be116af8 100644 --- a/build/docs/content/04-html.md +++ b/build/docs/content/04-html.md @@ -6,6 +6,13 @@ Gotenberg provides the endpoint `/convert/html` for HTML conversions. It accepts `POST` requests with a `multipart/form-data` Content-Type. +> **Attention:** currently, Google Chrome headless misbehaves if there are too many concurrent conversions. +> That's why for HTML, [URL](#url) and [Markdown](#markdown) conversions, the API does only 6 conversions at a time. +> The more concurrent requests, the more `504` HTTP codes the API will return. +> +> See the [scalability section](#scalability) to find how to mitigate this issue. +> You may also take a look at the [timeout section](#timeout). + ## Basic The only requirement is to send a file named `index.html`: it is the file diff --git a/build/docs/content/07-office.md b/build/docs/content/07-office.md index 3a2f7fbd..aff49807 100644 --- a/build/docs/content/07-office.md +++ b/build/docs/content/07-office.md @@ -6,6 +6,13 @@ Gotenberg provides the endpoint `/convert/office` for Office document conversion It accepts `POST` requests with a `multipart/form-data` Content-Type. +> **Attention:** currently, `unoconv` cannot perform concurrent conversions. +> That's why for Office conversions, the API does only one conversion at a time. +> The more concurrent requests, the more `504` HTTP codes the API will return. +> +> See the [scalability section](#scalability) to find how to mitigate this issue. +> You may also take a look at the [timeout section](#timeout). + ## Basic You may send one or more Office documents. Following file extensions are accepted: @@ -25,9 +32,7 @@ You may send one or more Office documents. Following file extensions are accepte All files will be merged into a single resulting PDF. -> **Attention:** currently, `unoconv` cannot perform concurrent conversions. -> That's why for Office conversions, the API does only one conversion at a time. -> See the [scalability section](#scalability) to find how to mitigate this issue. +> **Attention:** Gotenberg merges the PDF files alphabetically. ### cURL diff --git a/build/docs/content/09-timeout.md b/build/docs/content/09-timeout.md index a97ee0fd..3835b99c 100644 --- a/build/docs/content/09-timeout.md +++ b/build/docs/content/09-timeout.md @@ -5,6 +5,7 @@ title: Timeout All endpoints accept a form field named `waitTimeout`. The API will wait the given **seconds** before it considers the conversion to be unsucessful. +If unsucessful, it returns a `504` HTTP code. It takes a float as value (e.g `2.5` for 2.5 seconds). diff --git a/build/docs/content/13-ping.md b/build/docs/content/13-ping.md index 2039e682..669a972e 100644 --- a/build/docs/content/13-ping.md +++ b/build/docs/content/13-ping.md @@ -5,11 +5,6 @@ title: Ping Gotenberg provides the endpoint `/ping` for checking the API availability with a simple `GET` request. -This feature is especially useful for liveness/readiness probes in Kubernetes: - -* [Pod lifecycle](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes) -* [Configure Liveness and Readiness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/) - If `LOG_LEVEL` is `"DEBUG"`, it also returns details about the PM2 processes in JSON format. For instance: @@ -39,3 +34,5 @@ For instance: } ] ``` + +> if `LOG_LEVEL` is NOT `"DEBUG"`, no log entries are written. \ No newline at end of file diff --git a/build/docs/content/14-fonts.md b/build/docs/content/14-fonts.md index fa120864..752eedf9 100644 --- a/build/docs/content/14-fonts.md +++ b/build/docs/content/14-fonts.md @@ -7,7 +7,7 @@ By default, a handful of fonts are installed. Asian characters are also supporte If you wish to use more fonts, you will have to create your own image: ```Dockerfile -FROM thecodingmachine/gotenberg:5 +FROM thecodingmachine/gotenberg:6 RUN apt-get -y install yourfonts ``` \ No newline at end of file diff --git a/docs/index.html b/docs/index.html index 02a53776..721636d3 100755 --- a/docs/index.html +++ b/docs/index.html @@ -280,7 +280,8 @@ about what’s going on.

Default wait timeout -

By default, the API will wait 10 seconds before it considers the conversion to be unsuccessful.

+

By default, the API will wait 10 seconds before it considers the conversion to be unsuccessful. +If unsucessful, it returns a 504 HTTP code.

You may customize this timeout thanks to the environment variable DEFAULT_WAIT_TIMEOUT.

@@ -354,6 +355,15 @@ See the webhook timeout section.

It accepts POST requests with a multipart/form-data Content-Type.

+
+

Attention: currently, Google Chrome headless misbehaves if there are too many concurrent conversions. +That’s why for HTML, URL and Markdown conversions, the API does only 6 conversions at a time. +The more concurrent requests, the more 504 HTTP codes the API will return.

+ +

See the scalability section to find how to mitigate this issue. +You may also take a look at the timeout section.

+
+

Basic

@@ -874,6 +884,15 @@ $client->store($request, $dest);

It accepts POST requests with a multipart/form-data Content-Type.

+
+

Attention: currently, unoconv cannot perform concurrent conversions. +That’s why for Office conversions, the API does only one conversion at a time. +The more concurrent requests, the more 504 HTTP codes the API will return.

+ +

See the scalability section to find how to mitigate this issue. +You may also take a look at the timeout section.

+
+

Basic

@@ -898,9 +917,7 @@ $client->store($request, $dest);

All files will be merged into a single resulting PDF.

-

Attention: currently, unoconv cannot perform concurrent conversions. -That’s why for Office conversions, the API does only one conversion at a time. -See the scalability section to find how to mitigate this issue.

+

Attention: Gotenberg merges the PDF files alphabetically.

Timeout

All endpoints accept a form field named waitTimeout.

-

The API will wait the given seconds before it considers the conversion to be unsucessful.

+

The API will wait the given seconds before it considers the conversion to be unsucessful. +If unsucessful, it returns a 504 HTTP code.

It takes a float as value (e.g 2.5 for 2.5 seconds).

@@ -1342,13 +1360,6 @@ redirect a request to a Gotenberg container according to the round-robin strateg

Gotenberg provides the endpoint /ping for checking the API availability with a simple GET request.

-

This feature is especially useful for liveness/readiness probes in Kubernetes:

- - -

If LOG_LEVEL is "DEBUG", it also returns details about the PM2 processes in JSON format. For instance:

@@ -1378,6 +1389,10 @@ For instance:

] +
+

if LOG_LEVEL is NOT "DEBUG", no log entries are written.

+
+
@@ -1388,7 +1403,7 @@ For instance:

If you wish to use more fonts, you will have to create your own image:

-
FROM thecodingmachine/gotenberg:5
+
FROM thecodingmachine/gotenberg:6
 
 RUN apt-get -y install yourfonts