adalal/gotenberg
1
0
Fork 0
mirror of https://github.com/gotenberg/gotenberg.git synced 2026-08-18 05:02:15 +01:00
Code Issues Packages Projects Releases Wiki Activity

improving document

Browse Source
This commit is contained in:
Julien Neuhart
2019-09-30 17:16:40 +02:00
parent 8f721cd12a
commit 9968a816db
14 changed files with 78 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
build/docs/content/00-introduction.md
View File

@@ -6,7 +6,5 @@ title: Introduction
* HTML and Markdown conversions using Google Chrome headless * 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) * 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! * 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 * 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

3
build/docs/content/01-install.md
View File

@@ -36,7 +36,6 @@ services:
It may also be deployed with Kubernetes. It may also be deployed with Kubernetes.
Make sure to provide enough memory and CPU requests (for instance `512Mi` and `0.2` CPU). 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. > The more resources are granted, the quicker will be the conversions.
@@ -49,4 +48,4 @@ securityContext:
``` ```
In the following examples, we will assume your In the following examples, we will assume your
Gotenberg API is available at [http://localhost:3000](http://localhost:3000). Gotenberg API is available at [http://localhost:3000](http://localhost:3000).

2
build/docs/content/02-clients.md
View File

@@ -22,4 +22,4 @@ Then the PHP client:
```bash ```bash
$ composer require thecodingmachine/gotenberg-php-client $ composer require thecodingmachine/gotenberg-php-client
``` ```

7
build/docs/content/04-html.md
View File

@@ -6,13 +6,6 @@ Gotenberg provides the endpoint `/convert/html` for HTML conversions.
It accepts `POST` requests with a `multipart/form-data` Content-Type. 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 ## Basic
The only requirement is to send a file named `index.html`: it is the file The only requirement is to send a file named `index.html`: it is the file

7
build/docs/content/07-office.md
View File

@@ -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. 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 ## Basic
You may send one or more Office documents. Following file extensions are accepted: You may send one or more Office documents. Following file extensions are accepted:

2
build/docs/content/08-merge.md
View File

@@ -52,4 +52,4 @@ $files = [
$request = new MergeRequest($files); $request = new MergeRequest($files);
$dest = "result.pdf"; $dest = "result.pdf";
$client->store($request, $dest); $client->store($request, $dest);
``` ```

2
build/docs/content/09-timeout.md
View File

@@ -50,4 +50,4 @@ $request = new HTMLRequest($index);
$request->setWaitTimeout(2.5); $request->setWaitTimeout(2.5);
$dest = "result.pdf"; $dest = "result.pdf";
$client->store($request, $dest); $client->store($request, $dest);
``` ```

2
build/docs/content/10-webhook.md
View File

@@ -98,4 +98,4 @@ $request = new HTMLRequest($index);
$request->setWebhookURL('http://myapp.com/webhook/'); $request->setWebhookURL('http://myapp.com/webhook/');
$request->setWebhookURLTimeout(2.5); $request->setWebhookURLTimeout(2.5);
$resp = $client->post($request); $resp = $client->post($request);
``` ```

2
build/docs/content/11-result-filename.md
View File

@@ -47,4 +47,4 @@ $index = DocumentFactory::makeFromPath('index.html', 'index.html');
$request = new HTMLRequest($index); $request = new HTMLRequest($index);
$request->setResultFilename('foo.pdf'); $request->setResultFilename('foo.pdf');
$resp = $client->post($request); $resp = $client->post($request);
``` ```

27
build/docs/content/12-scalability.md
View File

@@ -2,6 +2,31 @@
title: Scalability 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. The API being stateless, you may scale it as much as you want.
For instance, using the following Docker Compose file: 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 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. redirect a request to a Gotenberg container according to the round-robin strategy.

34
build/docs/content/13-ping.md
View File

@@ -5,34 +5,8 @@ title: Ping
Gotenberg provides the endpoint `/ping` for checking the API availability with Gotenberg provides the endpoint `/ping` for checking the API availability with
a simple `GET` request. a simple `GET` request.
If `LOG_LEVEL` is `"DEBUG"`, it also returns details about the PM2 processes in JSON format. Currently this endpoint does nothing special. A better way to monitor
For instance: Gotenberg would be by checking the memory usage.
```json 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.
{
"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.

2
build/docs/content/14-fonts.md
View File

@@ -10,4 +10,4 @@ If you wish to use more fonts, you will have to create your own image:
FROM thecodingmachine/gotenberg:6 FROM thecodingmachine/gotenberg:6
RUN apt-get -y install yourfonts RUN apt-get -y install yourfonts
``` ```

2
build/docs/content/15-links.md
View File

@@ -5,4 +5,4 @@ title: Links
* Follow the progress on the [GitHub repository](https://github.com/thecodingmachine/gotenberg) * Follow the progress on the [GitHub repository](https://github.com/thecodingmachine/gotenberg)
* Follow [@gulnap](https://twitter.com/gulnap) on Twitter * Follow [@gulnap](https://twitter.com/gulnap) on Twitter
Psst: TheCodingMachine is always looking for [talented coders](https://coders.thecodingmachine.com). Psst: TheCodingMachine is always looking for [talented coders](https://coders.thecodingmachine.com).

93
docs/index.html
View File

@@ -120,8 +120,6 @@
<ul> <ul>
<li>HTML and Markdown conversions using Google Chrome headless</li> <li>HTML and Markdown conversions using Google Chrome headless</li>
<li>Office conversions (.txt, .rtf, .docx, .doc, .odt, .pptx, .ppt, .odp and so on) using <a href="https://github.com/dagwieers/unoconv">unoconv</a></li> <li>Office conversions (.txt, .rtf, .docx, .doc, .odt, .pptx, .ppt, .odp and so on) using <a href="https://github.com/dagwieers/unoconv">unoconv</a></li>
<li>Performance: Google Chrome and LibreOffice (unoconv) started once in the background thanks to PM2</li>
<li>Failure prevention: PM2 automatically restarts previous processes if they fail</li>
<li>Assets: send your header, footer, images, fonts, stylesheets and so on for converting your HTML and Markdown to beaufitul PDFs!</li> <li>Assets: send your header, footer, images, fonts, stylesheets and so on for converting your HTML and Markdown to beaufitul PDFs!</li>
<li>Easily interact with the API using our <a href="https://github.com/thecodingmachine/gotenberg-go-client">Go</a> and <a href="https://github.com/thecodingmachine/gotenberg-php-client">PHP</a> libraries</li> <li>Easily interact with the API using our <a href="https://github.com/thecodingmachine/gotenberg-go-client">Go</a> and <a href="https://github.com/thecodingmachine/gotenberg-php-client">PHP</a> libraries</li>
</ul> </ul>
@@ -173,8 +171,7 @@
<p>It may also be deployed with Kubernetes.</p> <p>It may also be deployed with Kubernetes.</p>
<p>Make sure to provide enough memory and CPU requests (for instance <code>512Mi</code> and <code>0.2</code> CPU). <p>Make sure to provide enough memory and CPU requests (for instance <code>512Mi</code> and <code>0.2</code> CPU).</p>
Otherwise the API will not be able to launch Google Chrome and LibreOffice (unoconv).</p>
<blockquote> <blockquote>
<p>The more resources are granted, the quicker will be the conversions.</p> <p>The more resources are granted, the quicker will be the conversions.</p>
@@ -356,15 +353,6 @@ See the <a href="#webhook.timeout">webhook timeout section</a>.</p>
<p>It accepts <code>POST</code> requests with a <code>multipart/form-data</code> Content-Type.</p> <p>It accepts <code>POST</code> requests with a <code>multipart/form-data</code> Content-Type.</p>
<blockquote>
<p><strong>Attention:</strong> currently, Google Chrome misbehaves if there are too many concurrent conversions.
That’s why for HTML, <a href="#url">URL</a> and <a href="#markdown">Markdown</a> conversions, the API does only 6 conversions at a time.
The more concurrent requests, the more <code>504</code> HTTP codes the API will return.</p>
<p>See the <a href="#scalability">scalability section</a> to find how to mitigate this issue.
You may also take a look at the <a href="#timeout">timeout section</a>.</p>
</blockquote>
<h2 class="Heading"><a class="Anchor" aria-hidden="true" id="html.basic" href="#html.basic"> <h2 class="Heading"><a class="Anchor" aria-hidden="true" id="html.basic" href="#html.basic">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Basic</h2> </a>Basic</h2>
@@ -885,15 +873,6 @@ $client-&gt;store($request, $dest);
<p>It accepts <code>POST</code> requests with a <code>multipart/form-data</code> Content-Type.</p> <p>It accepts <code>POST</code> requests with a <code>multipart/form-data</code> Content-Type.</p>
<blockquote>
<p><strong>Attention:</strong> currently, <code>unoconv</code> 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 <code>504</code> HTTP codes the API will return.</p>
<p>See the <a href="#scalability">scalability section</a> to find how to mitigate this issue.
You may also take a look at the <a href="#timeout">timeout section</a>.</p>
</blockquote>
<h2 class="Heading"><a class="Anchor" aria-hidden="true" id="office.basic" href="#office.basic"> <h2 class="Heading"><a class="Anchor" aria-hidden="true" id="office.basic" href="#office.basic">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Basic</h2> </a>Basic</h2>
@@ -1330,7 +1309,40 @@ $resp = $client-&gt;post($request);
<h1 class="Heading"><a class="Anchor" aria-hidden="true" id="scalability" href="#scalability"> <h1 class="Heading"><a class="Anchor" aria-hidden="true" id="scalability" href="#scalability">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg> <svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Scalability</h1> </a>Scalability</h1>
<p>The API being stateless, you may scale it as much as you want.</p> <p>Google Chrome and unoconv (LibreOffice) are intricate programs.</p>
<p>Gotenberg tries to abstract as much complexity as possible but it can
only do it to a certain extend.</p>
<p>For instance, Google Chrome misbehaves if there are too many concurrent conversions.
That’s why for <a href="#html">HTML</a>, <a href="#url">URL</a> and <a href="#markdown">Markdown</a> conversions, the API does only 6 conversions in parallel.
The more concurrent requests, the more <code>504</code> HTTP codes the API will return.</p>
<p>On another hand, for <a href="#office">Office</a> conversions, the API will start as many unoconv (LibreOffice) instances as there are
requests. The limitation here is the available memory.</p>
<h2 class="Heading"><a class="Anchor" aria-hidden="true" id="scalability.strategies" href="#scalability.strategies">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Strategies</h2>
<h3 class="Heading"><a class="Anchor" aria-hidden="true" id="scalability.strategies.increase_timeout" href="#scalability.strategies.increase_timeout">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Increase timeout</h3>
<p>This strategy is mostly for <a href="#html">HTML</a>, <a href="#url">URL</a> and <a href="#markdown">Markdown</a> conversions.</p>
<p>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.</p>
<blockquote>
<p>See <a href="#timeout">timeout section</a>.</p>
</blockquote>
<h3 class="Heading"><a class="Anchor" aria-hidden="true" id="scalability.strategies.scaling" href="#scalability.strategies.scaling">
<svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
</a>Scaling</h3>
<p>The API being stateless, you may scale it as much as you want.</p>
<p>For instance, using the following Docker Compose file:</p> <p>For instance, using the following Docker Compose file:</p>
@@ -1361,38 +1373,11 @@ redirect a request to a Gotenberg container according to the round-robin strateg
<p>Gotenberg provides the endpoint <code>/ping</code> for checking the API availability with <p>Gotenberg provides the endpoint <code>/ping</code> for checking the API availability with
a simple <code>GET</code> request.</p> a simple <code>GET</code> request.</p>
<p>If <code>LOG_LEVEL</code> is <code>&#34;DEBUG&#34;</code>, it also returns details about the PM2 processes in JSON format. <p>Currently this endpoint does nothing special. A better way to monitor
For instance:</p> Gotenberg would be by checking the memory usage.</p>
<pre class="chroma"><span class="p">[</span> <p>Also, as Google Chrome and unoconv (LibreOffice) are intricate programs, you should
<span class="p">{</span> restart your Gotenberg instances from time to time to ensure a nominal behaviour.</p>
<span class="nt">&#34;name&#34;</span><span class="p">:</span> <span class="s2">&#34;google-chrome-stable&#34;</span><span class="p">,</span>
<span class="nt">&#34;pm2_env&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;status&#34;</span><span class="p">:</span> <span class="s2">&#34;online&#34;</span><span class="p">,</span>
<span class="nt">&#34;restart_time&#34;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">},</span>
<span class="nt">&#34;monit&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;memory&#34;</span><span class="p">:</span> <span class="mi">72294400</span><span class="p">,</span>
<span class="nt">&#34;cpu&#34;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">}</span>
<span class="p">},</span>
<span class="p">{</span>
<span class="nt">&#34;name&#34;</span><span class="p">:</span> <span class="s2">&#34;unoconv&#34;</span><span class="p">,</span>
<span class="nt">&#34;pm2_env&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;status&#34;</span><span class="p">:</span> <span class="s2">&#34;online&#34;</span><span class="p">,</span>
<span class="nt">&#34;restart_time&#34;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">},</span>
<span class="nt">&#34;monit&#34;</span><span class="p">:</span> <span class="p">{</span>
<span class="nt">&#34;memory&#34;</span><span class="p">:</span> <span class="mi">71000064</span><span class="p">,</span>
<span class="nt">&#34;cpu&#34;</span><span class="p">:</span> <span class="mi">0</span>
<span class="p">}</span>
<span class="p">}</span>
<span class="p">]</span>
</pre>
<blockquote>
<p>if <code>LOG_LEVEL</code> is <strong>not</strong> <code>&#34;DEBUG&#34;</code>, no log entries are written.</p>
</blockquote>
</div> </div>