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

5.0.0 (#66)

Browse Source
This commit is contained in:
Julien Neuhart
2019-04-14 17:07:45 +02:00
committed by GitHub
parent c4222e0981
commit 194670c3bf
63 changed files with 2114 additions and 1503 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -6,7 +6,7 @@ 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 (unoconv) started once in the background thanks to PM2
* Performance: Google Chrome and LibreOffice (unoconv) 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

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

@@ -7,12 +7,14 @@ Gotenberg is shipped within a Docker image.
You may start it with:
```bash
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:4
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:5
```
> The API will be available at [http://localhost:3000](http://localhost:3000).
Or add it in your Docker Compose stack:
## Docker Compose
You may also add it in your Docker Compose stack:
```yaml
version: '3'
@@ -22,37 +24,19 @@ services:
# your others services
gotenberg:
image: thecodingmachine/gotenberg:4
image: thecodingmachine/gotenberg:5
```
> The API will be available under `gotenberg:3000` in your Docker Compose network.
## Kubernetes
It may also be deployed with Kubernetes.
> In 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).
>
> Also note the more resources are granted, the quicker will be the conversions.
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.
In the following examples, we will assume your
Gotenberg API is available at [http://localhost:3000](http://localhost:3000).
## Go client
```bash
$ go get -u github.com/thecodingmachine/gotenberg-go-client/v4
```
## PHP client
Unless your project already has a PSR7 `HttpClient`, install `php-http/guzzle6-adapter`:
```bash
$ composer require php-http/guzzle6-adapter
```
Then the PHP client:
```bash
$ composer require thecodingmachine/gotenberg-php-client
```
Gotenberg API is available at [http://localhost:3000](http://localhost:3000).

25
build/docs/content/02-clients.md Normal file
View File

@@ -0,0 +1,25 @@
---
title: Clients
---
We provide clients in various languages for easing the interactions with the API.
## Go client
```bash
$ go get -u github.com/thecodingmachine/gotenberg-go-client/v5
```
## PHP client
Unless your project already has a PSR7 `HttpClient`, install `php-http/guzzle6-adapter`:
```bash
$ composer require php-http/guzzle6-adapter
```
Then the PHP client:
```bash
$ composer require thecodingmachine/gotenberg-php-client
```

33
build/docs/content/03-environment-variables.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Environment variables
---
You may customize the API behaviour thanks to environment variables.
## Disable Google Chrome
In order to save some resources, the Gotenberg image accepts the environment variable `DISABLE_GOOGLE_CHROME`.
It takes the strings `"0"` or `"1"` as value.
> If Google Chrome is disabled, the following conversions will **not** be available anymore:
> [HTML](#html), [URL](#url) and [Markdown](#markdown)
## Disable LibreOffice (unoconv)
You may also disable LibreOffice (unoconv) with `DISABLE_UNOCONV`.
> If LibreOffice (unoconv) is disabled, the following conversion will **not** be available anymore:
> [Office](#office)
## Default wait timeout
By default, the API will wait 10 seconds before it considers the conversion to be unsuccessful.
You may customize this timeout thanks to the environment variable `DEFAULT_WAIT_TIMEOUT`.
It takes a string representation of a float as value (e.g `"2.5"` for 2.5 seconds).
> The default timeout may also be overridden per request thanks to the form field `waitTimeout`.
> See the [timeout section](#timeout).

74
build/docs/content/02-html.md → build/docs/content/04-html.md
View File

@@ -39,7 +39,7 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
@@ -113,13 +113,13 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.SetHeader("header.html")
req.SetFooter("footer.html")
req.Header("header.html")
req.Footer("footer.html")
dest := "result.pdf"
c.Store(req, dest)
}
@@ -186,9 +186,6 @@ You may also use *remote* paths for Google fonts, images and so on.
> If you want to install fonts directly in the Gotenberg Docker image,
> see to the [fonts section](#fonts).
>
> For web fonts (Google fonts), there is a timeout of 500ms by default. You may update
> this value thanks to the form field `webFontsTimeout`.
### cURL
@@ -206,12 +203,12 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.SetAssets("font.woff", "img.gif", "style.css")
req.Assets("font.woff", "img.gif", "style.css")
dest := "result.pdf"
c.Store(req, dest)
}
@@ -243,8 +240,7 @@ You may also customize the resulting PDF format.
By default, it will be rendered with `A4` size, `1 inch` margins and `portrait` orientation.
> Paper size and margins have to be provided in `inches`.
> Also, you have to set both `paperWidth` and `paperHeight`. Same for margins.
> Paper size and margins have to be provided in `inches`. Same for margins.
### cURL
@@ -266,14 +262,14 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.SetPaperSize(gotenberg.A4)
req.SetMargins(gotenberg.NoMargins)
req.SetLandscape(true)
req.PaperSize(gotenberg.A4)
req.Margins(gotenberg.NoMargins)
req.Landscape(true)
dest := "result.pdf"
c.Store(req, dest)
}
@@ -295,4 +291,52 @@ $request->setMargins(Request::NO_MARGINS);
$request->setLandscape(true);
$dest = "result.pdf";
$client->store($request, $dest);
```
## Wait delay
In some cases, you may want to wait a certain amount of time to make sure the
page you're trying to generate is fully rendered.
> The wait delay is a duration in **seconds** (e.g `2.5` for 2.5 seconds).
### cURL
```bash
$ curl --request POST \
--url http://localhost:3000/convert/html \
--header 'Content-Type: multipart/form-data' \
--form files=@index.html \
--form waitDelay=5.5 \
-o result.pdf
```
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.WaitDelay(5.5)
dest := "result.pdf"
c.Store(req, dest)
}
```
### PHP
```php
use TheCodingMachine\Gotenberg\Client;
use TheCodingMachine\Gotenberg\DocumentFactory;
use TheCodingMachine\Gotenberg\HTMLRequest;
use TheCodingMachine\Gotenberg\Request;
$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client());
$index = DocumentFactory::makeFromPath('index.html', 'index.html');
$request = new HTMLRequest($index);
$request->setWaitDelay(5.5);
$dest = "result.pdf";
$client->store($request, $dest);
```

4
build/docs/content/03-url.md → build/docs/content/05-url.md
View File

@@ -31,12 +31,12 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req := gotenberg.NewURLRequest("https://google.com")
req.SetMargins(gotenberg.NoMargins)
req.Margins(gotenberg.NoMargins)
dest := "result.pdf"
c.Store(req, dest)
}

2
build/docs/content/04-markdown.md → build/docs/content/06-markdown.md
View File

@@ -42,7 +42,7 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}

6
build/docs/content/05-office.md → build/docs/content/07-office.md
View File

@@ -43,7 +43,7 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
@@ -90,12 +90,12 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewOfficeRequest("document.docx")
req.SetLandscape(true)
req.Landscape(true)
dest := "result.pdf"
c.Store(req, dest)
}

14
build/docs/content/08-filename.md
View File

@@ -1,14 +0,0 @@
---
title: Filename
---
All endpoints accept a form field named `filename`.
If provided, the API will return the resulting PDF file with the given filename.
Otherwise a random filename is used.
> The Go and PHP libraries do not provide a way to set this form field.
> However, you may hijack the response from the API or store the resulting PDF
> using a custom filename.
>
> **Attention:** this feature does not work if the form field `webhookURL` is given.

6
build/docs/content/06-merge.md → build/docs/content/08-merge.md
View File

@@ -2,7 +2,7 @@
title: Merge
---
Gotenberg provides the endpoint `/merge` for merging PDFs.
Gotenberg provides the endpoint `/convert/merge` for merging PDFs.
It accepts `POST` requests with a `multipart/form-data` Content-Type.
@@ -17,7 +17,7 @@ will merge them and return the resulting PDF file.
```bash
$ curl --request POST \
--url http://localhost:3000/merge \
--url http://localhost:3000/convert/merge \
--header 'Content-Type: multipart/form-data' \
--form files=@file.pdf \
--form files=@file2.pdf \
@@ -27,7 +27,7 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}

52
build/docs/content/09-timeout.md Normal file
View File

@@ -0,0 +1,52 @@
---
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.
It takes a float as value (e.g `2.5` for 2.5 seconds).
> You may also define this value globally: see the [environment variables](#environment_variables.default_wait_timeout) section.
## Examples
### cURL
```bash
$ curl --request POST \
--url http://localhost:3000/convert/html \
--header 'Content-Type: multipart/form-data' \
--form files=@index.html \
--form waitTimeout=2.5
```
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.WaitTimeout(2.5)
resp, _ := c.Post(req)
}
```
### PHP
```php
use TheCodingMachine\Gotenberg\Client;
use TheCodingMachine\Gotenberg\DocumentFactory;
use TheCodingMachine\Gotenberg\HTMLRequest;
use TheCodingMachine\Gotenberg\Request;
$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client());
$index = DocumentFactory::makeFromPath('index.html', 'index.html');
$request = new HTMLRequest($index);
$request->setWaitTimeout(2.5);
$dest = "result.pdf";
$client->store($request, $dest);
```

5
build/docs/content/07-webhook.md → build/docs/content/10-webhook.md
View File

@@ -24,13 +24,12 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v4"
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.SetWebhookURL("http://myapp.com/webhook/")
dest := "result.pdf"
req.WebhookURL("http://myapp.com/webhook/")
resp, _ := c.Post(req)
}
```

50
build/docs/content/11-result-filename.md Normal file
View File

@@ -0,0 +1,50 @@
---
title: Result filename
---
All endpoints accept a form field named `resultFilename`.
If provided, the API will return the resulting PDF file with the given filename.
Otherwise a random filename is used.
> **Attention:** this feature does not work if the form field `webhookURL` is given.
## Examples
### cURL
```bash
$ curl --request POST \
--url http://localhost:3000/convert/html \
--header 'Content-Type: multipart/form-data' \
--form files=@index.html \
--form resultFilename='foo.pdf'
```
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v5"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.ResultFilename("foo.pdf")
resp, _ := c.Post(req)
}
```
### PHP
```php
use TheCodingMachine\Gotenberg\Client;
use TheCodingMachine\Gotenberg\DocumentFactory;
use TheCodingMachine\Gotenberg\HTMLRequest;
use TheCodingMachine\Gotenberg\Request;
$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client());
$index = DocumentFactory::makeFromPath('index.html', 'index.html');
$request = new HTMLRequest($index);
$request->setResultFilename('foo.pdf');
$resp = $client->post($request);
```

2
build/docs/content/09-scalability.md → build/docs/content/12-scalability.md
View File

@@ -14,7 +14,7 @@ services:
# your others services
gotenberg:
image: thecodingmachine/gotenberg:4
image: thecodingmachine/gotenberg:5
```
You may now launch your services using:

2
build/docs/content/10-liveness.md → build/docs/content/13-ping.md
View File

@@ -1,5 +1,5 @@
---
title: Liveness
title: Ping
---
Gotenberg provides the endpoint `/ping` for checking the API availability with

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

@@ -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:4
FROM thecodingmachine/gotenberg:5
RUN apt-get -y install yourfonts
```

0
build/docs/content/12-links.md → build/docs/content/15-links.md
View File