adalal/gotenberg
1
0
Fork 0
mirror of https://github.com/gotenberg/gotenberg.git synced 2026-08-16 04:12:16 +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

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>