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

updating documentation according to changes

Browse Source
This commit is contained in:
Julien Neuhart
2019-08-20 16:20:42 +02:00
parent 95c6ecb724
commit db6cddefd4
16 changed files with 328 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -4,14 +4,14 @@ title: Install
Gotenberg is shipped within a Docker image.
> It uses a dedicated non-root user called `gotenberg` with uid and gid `1001`.
You may start it with:
```bash
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:5
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:6
```
All processes in the Docker container runs as a dedicated non-root user called `gotenberg` with user id `1001` from the working dir `/gotenberg`.
> The API will be available at [http://localhost:3000](http://localhost:3000).
## Docker Compose
@@ -26,7 +26,7 @@ services:
# your others services
gotenberg:
image: thecodingmachine/gotenberg:5
image: thecodingmachine/gotenberg:6
```
> The API will be available under `gotenberg:3000` in your Docker Compose network.
@@ -40,7 +40,8 @@ Otherwise the API will not be able to launch Google Chrome and LibreOffice (unoc
> The more resources are granted, the quicker will be the conversions.
Also, in the deployment spec of the pod, specify the uid `1001` of the user `gotenberg`:
In the deployment specification of the pod, also specify the uid `1001` of the user `gotenberg`:
```
securityContext:
privileged: false

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

@@ -7,7 +7,7 @@ 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
$ go get -u github.com/thecodingmachine/gotenberg-go-client/v6
```
## PHP client

58
build/docs/content/03-environment-variables.md
View File

@@ -4,6 +4,25 @@ title: Environment variables
You may customize the API behaviour thanks to environment variables.
## Log level
The API provides structured logging allowing you to have relevant information
about what's going on.
> If a TTY is attached, the log entries are displayed in text format with colors, otherwise in JSON format.
You may customize the severity of the log entries thanks to the environment variable `LOG_LEVEL`.
It accepts one of the following severities: `"DEBUG"`, `"INFO"` (default) and `"ERROR"`.
## Default listen port
By default, the API will listen on port `3000`.
You may customize this value with the environment variable `DEFAULT_LISTEN_PORT`.
This environment variable accepts any string that can be turned into a port number.
## Disable Google Chrome
In order to save some resources, the Gotenberg image accepts the environment variable `DISABLE_GOOGLE_CHROME`.
@@ -31,26 +50,41 @@ It takes a string representation of a float as value (e.g `"2.5"` for 2.5 second
> The default timeout may also be overridden per request thanks to the form field `waitTimeout`.
> See the [timeout section](#timeout).
## Disable logging on healthcheck
## Maximum wait timeout
By default, the API will add a log entry when the [healthcheck endpoint](#ping) is called.
By default, the value of the form field `waitTimeout` cannot be more than 30 seconds.
You may turn off this logging so as to avoid unnecessary entries in your logs with the environment variable `DISABLE_HEALTHCHECK_LOGGING`.
You may increase or decrease this limit thanks to the environment variable `MAXIMUM_WAIT_TIMEOUT`.
This environment variable operates in the same manner as the `DISABLE_GOOGLE_CHROME` and `DISABLE_UNOCONV` variables operate in that it accepts the strings `"0"` or `"1"` as values, where `"1"` is enabled.
It takes a string representation of a float as value (e.g `"2.5"` for 2.5 seconds).
## Default listen port
## Default webhook URL timeout
By default, the API will listen on port `3000`. For most use cases this is perfectly fine, but at times there may be cases where you need to change this due to port conflicts.
By default, the API will wait 10 seconds before it considers the sending of the resulting PDF to be unsuccessful.
You may customize this port location with the environment variable `DEFAULT_LISTEN_PORT`.
> See the [webhook section](#webhook).
This environment variable accepts any string that can be turned into a port number (e.g., the string `"0"` up to the string `"65535"`).
You may customize this timeout thanks to the environment variable `DEFAULT_WEBHOOK_URL_TIMEOUT`.
## Debug logging of process startup
It takes a string representation of a float as value (e.g `"2.5"` for 2.5 seconds).
By default, `stdout` and `stderr` messages from the started processes are disabled.
> The default timeout may also be overridden per request thanks to the form field `webhookURLTimeout`.
> See the [webhook timeout section](#webhook.timeout).
You may enable some debug logging from starting the process by setting the environment variable `DEBUG_PROCESS_STARTUP`.
## Maximum webhook URL timeout
This environment variable operates in the same manner as the `DISABLE_GOOGLE_CHROME` and `DISABLE_UNOCONV` variables operate in that it accepts the strings `"0"` or `"1"` as values, where `1` means `true`.
By default, the value of the form field `webhookURLTimeout` cannot be more than 30 seconds.
You may increase or decrease this limit thanks to the environment variable `MAXIMUM_WEBHOOK_URL_TIMEOUT`.
It takes a string representation of a float as value (e.g `"2.5"` for 2.5 seconds).
## Maximum wait delay
By default, the value of the form field `waitDelay` cannot be more than 10 seconds.
> See the [wait delay section](#html.wait_delay).
You may increase or decrease this limit thanks to the environment variable `MAXIMUM_WAIT_DELAY`.
It takes a string representation of a float as value (e.g `"2.5"` for 2.5 seconds).

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

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

2
build/docs/content/05-url.md
View File

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

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

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

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

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

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

@@ -2,7 +2,7 @@
title: Merge
---
Gotenberg provides the endpoint `/convert/merge` for merging PDFs.
Gotenberg provides the endpoint `/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/convert/merge \
--url http://localhost:3000/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/v5"
import "github.com/thecodingmachine/gotenberg-go-client/v6"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}

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

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

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

@@ -24,7 +24,7 @@ $ curl --request POST \
### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v5"
import "github.com/thecodingmachine/gotenberg-go-client/v6"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
@@ -46,4 +46,56 @@ $index = DocumentFactory::makeFromPath('index.html', 'index.html');
$request = new HTMLRequest($index);
$request->setWebhookURL('http://myapp.com/webhook/');
$resp = $client->post($request);
```
## Timeout
If a `webhookURL` is provided, you may also send a form field named `webhookURLTimeout`.
The API will wait the given **seconds** before it considers the sending of the resulting PDF 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_webhook_url_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 webhookURL='http://myapp.com/webhook/' \
--form webhookURLTimeout=2.5
```
#### Go
```golang
import "github.com/thecodingmachine/gotenberg-go-client/v6"
func main() {
c := &gotenberg.Client{Hostname: "http://localhost:3000"}
req, _ := gotenberg.NewHTMLRequest("index.html")
req.WebhookURL("http://myapp.com/webhook/")
req.WebhookURLTimeout(2.5)
resp, _ := c.Post(req)
}
```
#### PHP
```php
use TheCodingMachine\Gotenberg\Client;
use TheCodingMachine\Gotenberg\DocumentFactory;
use TheCodingMachine\Gotenberg\HTMLRequest;
$client = new Client('http://localhost:3000', new \Http\Adapter\Guzzle6\Client());
$index = DocumentFactory::makeFromPath('index.html', 'index.html');
$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

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

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

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

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

@@ -8,4 +8,32 @@ a simple `GET` request.
This feature is especially useful for liveness/readiness probes in Kubernetes:
* [Pod lifecycle](https://kubernetes.io/docs/concepts/workloads/pods/pod-lifecycle/#container-probes)
* [Configure Liveness and Readiness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
* [Configure Liveness and Readiness Probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-probes/)
If `LOG_LEVEL` is `"DEBUG"`, it also returns details about the PM2 processes in JSON format.
For instance:
```json
[
{
"name": "google-chrome-stable",
"pm2_env": {
"status": "online"
},
"monit": {
"memory": 73826304,
"cpu": 0
}
},
{
"name": "unoconv",
"pm2_env": {
"status": "online"
},
"monit": {
"memory": 70914048,
"cpu": 0
}
}
]
```