diff --git a/build/docs/content/00-introduction.md b/build/docs/content/00-introduction.md index 1c6728e1..21b6a0a4 100644 --- a/build/docs/content/00-introduction.md +++ b/build/docs/content/00-introduction.md @@ -6,7 +6,5 @@ title: Introduction * HTML and Markdown conversions using Google Chrome headless * Office conversions (.txt, .rtf, .docx, .doc, .odt, .pptx, .ppt, .odp and so on) using [unoconv](https://github.com/dagwieers/unoconv) -* Performance: Google Chrome and LibreOffice started once in the background thanks to PM2 -* Failure prevention: PM2 automatically restarts previous processes if they fail * Assets: send your header, footer, images, fonts, stylesheets and so on for converting your HTML and Markdown to beaufitul PDFs! -* Easily interact with the API using our [Go](https://github.com/thecodingmachine/gotenberg-go-client) and [PHP](https://github.com/thecodingmachine/gotenberg-php-client) libraries \ No newline at end of file +* Easily interact with the API using our [Go](https://github.com/thecodingmachine/gotenberg-go-client) and [PHP](https://github.com/thecodingmachine/gotenberg-php-client) libraries diff --git a/build/docs/content/01-install.md b/build/docs/content/01-install.md index 9e344f20..6054cf75 100644 --- a/build/docs/content/01-install.md +++ b/build/docs/content/01-install.md @@ -36,7 +36,6 @@ services: It may also be deployed with Kubernetes. Make sure to provide enough memory and CPU requests (for instance `512Mi` and `0.2` CPU). -Otherwise the API will not be able to launch Google Chrome and LibreOffice (unoconv). > The more resources are granted, the quicker will be the conversions. @@ -49,4 +48,4 @@ securityContext: ``` In the following examples, we will assume your -Gotenberg API is available at [http://localhost:3000](http://localhost:3000). \ No newline at end of file +Gotenberg API is available at [http://localhost:3000](http://localhost:3000). diff --git a/build/docs/content/02-clients.md b/build/docs/content/02-clients.md index 59ecd1e6..64de1e23 100644 --- a/build/docs/content/02-clients.md +++ b/build/docs/content/02-clients.md @@ -22,4 +22,4 @@ Then the PHP client: ```bash $ composer require thecodingmachine/gotenberg-php-client -``` \ No newline at end of file +``` diff --git a/build/docs/content/04-html.md b/build/docs/content/04-html.md index 05cd7f5b..8f1e5070 100644 --- a/build/docs/content/04-html.md +++ b/build/docs/content/04-html.md @@ -6,13 +6,6 @@ Gotenberg provides the endpoint `/convert/html` for HTML conversions. It accepts `POST` requests with a `multipart/form-data` Content-Type. -> **Attention:** currently, Google Chrome 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 aff49807..39e91e37 100644 --- a/build/docs/content/07-office.md +++ b/build/docs/content/07-office.md @@ -6,13 +6,6 @@ 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: diff --git a/build/docs/content/08-merge.md b/build/docs/content/08-merge.md index 59a3e4d8..49ac0b2b 100644 --- a/build/docs/content/08-merge.md +++ b/build/docs/content/08-merge.md @@ -52,4 +52,4 @@ $files = [ $request = new MergeRequest($files); $dest = "result.pdf"; $client->store($request, $dest); -``` \ No newline at end of file +``` diff --git a/build/docs/content/09-timeout.md b/build/docs/content/09-timeout.md index 3835b99c..9392b84f 100644 --- a/build/docs/content/09-timeout.md +++ b/build/docs/content/09-timeout.md @@ -50,4 +50,4 @@ $request = new HTMLRequest($index); $request->setWaitTimeout(2.5); $dest = "result.pdf"; $client->store($request, $dest); -``` \ No newline at end of file +``` diff --git a/build/docs/content/10-webhook.md b/build/docs/content/10-webhook.md index b94743ba..fff2456d 100644 --- a/build/docs/content/10-webhook.md +++ b/build/docs/content/10-webhook.md @@ -98,4 +98,4 @@ $request = new HTMLRequest($index); $request->setWebhookURL('http://myapp.com/webhook/'); $request->setWebhookURLTimeout(2.5); $resp = $client->post($request); -``` \ No newline at end of file +``` diff --git a/build/docs/content/11-result-filename.md b/build/docs/content/11-result-filename.md index 634962e7..aabb4177 100644 --- a/build/docs/content/11-result-filename.md +++ b/build/docs/content/11-result-filename.md @@ -47,4 +47,4 @@ $index = DocumentFactory::makeFromPath('index.html', 'index.html'); $request = new HTMLRequest($index); $request->setResultFilename('foo.pdf'); $resp = $client->post($request); -``` \ No newline at end of file +``` diff --git a/build/docs/content/12-scalability.md b/build/docs/content/12-scalability.md index a58c329c..18aa9c18 100644 --- a/build/docs/content/12-scalability.md +++ b/build/docs/content/12-scalability.md @@ -2,6 +2,31 @@ title: Scalability --- +Google Chrome and unoconv (LibreOffice) are intricate programs. + +Gotenberg tries to abstract as much complexity as possible but it can +only do it to a certain extend. + +For instance, Google Chrome misbehaves if there are too many concurrent conversions. +That's why for [HTML](#html), [URL](#url) and [Markdown](#markdown) conversions, the API does only 6 conversions in parallel. +The more concurrent requests, the more `504` HTTP codes the API will return. + +On another hand, for [Office](#office) conversions, the API will start as many unoconv (LibreOffice) instances as there are +requests. The limitation here is the available memory. + +## Strategies + +### Increase timeout + +This strategy is mostly for [HTML](#html), [URL](#url) and [Markdown](#markdown) conversions. + +You may increase the conversion timeout. In other word, you accept that a conversion takes more time +if there are more than 6 conversions in parallel. + +> See [timeout section](#timeout). + +### Scaling + The API being stateless, you may scale it as much as you want. For instance, using the following Docker Compose file: @@ -24,4 +49,4 @@ $ docker-compose up --scale gotenberg=your_number_of_instances ``` When requesting the Gotenberg service with your client(s), Docker will automatically -redirect a request to a Gotenberg container according to the round-robin strategy. \ No newline at end of file +redirect a request to a Gotenberg container according to the round-robin strategy. diff --git a/build/docs/content/13-ping.md b/build/docs/content/13-ping.md index 3da6ea70..3d661698 100644 --- a/build/docs/content/13-ping.md +++ b/build/docs/content/13-ping.md @@ -5,34 +5,8 @@ title: Ping Gotenberg provides the endpoint `/ping` for checking the API availability with a simple `GET` request. -If `LOG_LEVEL` is `"DEBUG"`, it also returns details about the PM2 processes in JSON format. -For instance: +Currently this endpoint does nothing special. A better way to monitor +Gotenberg would be by checking the memory usage. -```json -[ - { - "name": "google-chrome-stable", - "pm2_env": { - "status": "online", - "restart_time": 0 - }, - "monit": { - "memory": 72294400, - "cpu": 0 - } - }, - { - "name": "unoconv", - "pm2_env": { - "status": "online", - "restart_time": 0 - }, - "monit": { - "memory": 71000064, - "cpu": 0 - } - } -] -``` - -> if `LOG_LEVEL` is **not** `"DEBUG"`, no log entries are written. \ No newline at end of file +Also, as Google Chrome and unoconv (LibreOffice) are intricate programs, you should +restart your Gotenberg instances from time to time to ensure a nominal behaviour. diff --git a/build/docs/content/14-fonts.md b/build/docs/content/14-fonts.md index 752eedf9..18d7c3ec 100644 --- a/build/docs/content/14-fonts.md +++ b/build/docs/content/14-fonts.md @@ -10,4 +10,4 @@ If you wish to use more fonts, you will have to create your own image: FROM thecodingmachine/gotenberg:6 RUN apt-get -y install yourfonts -``` \ No newline at end of file +``` diff --git a/build/docs/content/15-links.md b/build/docs/content/15-links.md index 4f2dbf3f..4c778b6f 100644 --- a/build/docs/content/15-links.md +++ b/build/docs/content/15-links.md @@ -5,4 +5,4 @@ title: Links * Follow the progress on the [GitHub repository](https://github.com/thecodingmachine/gotenberg) * Follow [@gulnap](https://twitter.com/gulnap) on Twitter -Psst: TheCodingMachine is always looking for [talented coders](https://coders.thecodingmachine.com). \ No newline at end of file +Psst: TheCodingMachine is always looking for [talented coders](https://coders.thecodingmachine.com). diff --git a/docs/index.html b/docs/index.html index 7036fb32..261ec674 100755 --- a/docs/index.html +++ b/docs/index.html @@ -120,8 +120,6 @@ @@ -173,8 +171,7 @@

It may also be deployed with Kubernetes.

-

Make sure to provide enough memory and CPU requests (for instance 512Mi and 0.2 CPU). -Otherwise the API will not be able to launch Google Chrome and LibreOffice (unoconv).

+

Make sure to provide enough memory and CPU requests (for instance 512Mi and 0.2 CPU).

The more resources are granted, the quicker will be the conversions.

@@ -356,15 +353,6 @@ See the webhook timeout section.

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

-
-

Attention: currently, Google Chrome 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

@@ -885,15 +873,6 @@ $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

@@ -1330,7 +1309,40 @@ $resp = $client->post($request);

Scalability

-

The API being stateless, you may scale it as much as you want.

+

Google Chrome and unoconv (LibreOffice) are intricate programs.

+ +

Gotenberg tries to abstract as much complexity as possible but it can +only do it to a certain extend.

+ +

For instance, Google Chrome misbehaves if there are too many concurrent conversions. +That’s why for HTML, URL and Markdown conversions, the API does only 6 conversions in parallel. +The more concurrent requests, the more 504 HTTP codes the API will return.

+ +

On another hand, for Office conversions, the API will start as many unoconv (LibreOffice) instances as there are +requests. The limitation here is the available memory.

+ +

Strategies

+ +

Increase timeout

+ +

This strategy is mostly for HTML, URL and Markdown conversions.

+ +

You may increase the conversion timeout. In other word, you accept that a conversion takes more time +if there are more than 6 conversions in parallel.

+ +
+

See timeout section.

+
+ +

Scaling

+ +

The API being stateless, you may scale it as much as you want.

For instance, using the following Docker Compose file:

@@ -1361,38 +1373,11 @@ 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.

-

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

+

Currently this endpoint does nothing special. A better way to monitor +Gotenberg would be by checking the memory usage.

-
[
-    {
-        "name": "google-chrome-stable",
-        "pm2_env": {
-            "status": "online",
-            "restart_time": 0
-        },
-        "monit": {
-            "memory": 72294400,
-            "cpu": 0
-        }
-    },
-    {
-        "name": "unoconv",
-        "pm2_env": {
-            "status": "online",
-            "restart_time": 0
-        },
-        "monit": {
-            "memory": 71000064,
-            "cpu": 0
-        }
-    }
-]
-
- -
-

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

-
+

Also, as Google Chrome and unoconv (LibreOffice) are intricate programs, you should +restart your Gotenberg instances from time to time to ensure a nominal behaviour.