adalal/gotenberg
1
0
Fork 0
mirror of https://github.com/gotenberg/gotenberg.git synced 2026-08-14 03:12:14 +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
* 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
* 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.
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).
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
$ 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.
> **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

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.
> **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:

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

@@ -52,4 +52,4 @@ $files = [
$request = new MergeRequest($files);
$dest = "result.pdf";
$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);
$dest = "result.pdf";
$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->setWebhookURLTimeout(2.5);
$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->setResultFilename('foo.pdf');
$resp = $client->post($request);
```
```

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

@@ -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.
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
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.
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.

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
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 [@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>
<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>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>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>
@@ -173,8 +171,7 @@
<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).
Otherwise the API will not be able to launch Google Chrome and LibreOffice (unoconv).</p>
<p>Make sure to provide enough memory and CPU requests (for instance <code>512Mi</code> and <code>0.2</code> CPU).</p>
<blockquote>
<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>
<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">
<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>
@@ -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>
<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">
<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>
@@ -1330,7 +1309,40 @@ $resp = $client-&gt;post($request);
<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>
</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>
@@ -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
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.
For instance:</p>
<p>Currently this endpoint does nothing special. A better way to monitor
Gotenberg would be by checking the memory usage.</p>
<pre class="chroma"><span class="p">[</span>
<span class="p">{</span>
<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>
<p>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.</p>
</div>