mirror of
https://github.com/gotenberg/gotenberg.git
synced 2026-08-08 00:22:14 +01:00
updating README
This commit is contained in:
Julien Neuhart
@@ -28,24 +28,89 @@
|
||||
|
||||
# Menu
|
||||
|
||||
* [Quick start](#quick-start)
|
||||
* [API](#api)
|
||||
* [Custom implementation](#custom-implementation)
|
||||
* [Usage](#usage)
|
||||
* [Security][#security]
|
||||
* [Scalability](#scalability)
|
||||
* [Custom implementation](#custom-implementation)
|
||||
|
||||
## Quick start
|
||||
## Usage
|
||||
|
||||
Let's say you're starting the API using this simple command:
|
||||
|
||||
```sh
|
||||
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:{{ .Orbit.Branch }}
|
||||
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:1.0.0
|
||||
```
|
||||
|
||||
The API is now available through `http://127.0.0.1:3000`.
|
||||
The API is now available on your host under `http://127.0.0.1:3000`.
|
||||
|
||||
## API
|
||||
It accepts `POST` requests with a `multipart/form-data` Content-Type. Your form data should provide one or more files to convert.
|
||||
It currently accepts the following:
|
||||
|
||||
* Markdown files
|
||||
* HTML files
|
||||
* Office documents (.docx, .doc, .odt, .pptx, .ppt, .odp and so on)
|
||||
* PDF files (if more than one file to convert)
|
||||
|
||||
**Heads up:** the API relies on the file extension to determine which library to use for conversion.
|
||||
|
||||
There are two use cases:
|
||||
|
||||
* If you send one file, it will convert it and return the resulting PDF.
|
||||
* If many files, it will convert them to PDF, merge the resulting PDFs into a single PDF and return it.
|
||||
|
||||
## Security
|
||||
|
||||
The API does not provide any authentication mechanisms. Make sure to not put it on a public facing port and your client(s) should always
|
||||
controls what's is sent to the API.
|
||||
|
||||
## Scalability
|
||||
|
||||
Some libraries like **unoconv** cannot perform concurrent conversions. That's why the API does only one conversion at a time.
|
||||
If your API is under heavy load, a request will take time to be processed.
|
||||
|
||||
Fortunately, you may pass through this limitation by scaling the API.
|
||||
|
||||
In the following example, I'll demonstrate how to do some vertical scaling (= on the same machine) with Docker Compose, but of course horizontal scaling works too!
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
|
||||
# your other services
|
||||
|
||||
gotenberg-proxy:
|
||||
# Traefik is a powerful HTTP reverse proxy which allowx us to do some load-balancing.
|
||||
# It provides various methods of load-balancing which are not described here.
|
||||
# More information: https://traefik.io/
|
||||
image: traefik:1.5-alpine
|
||||
command: --docker --logLevel=DEBUG
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
|
||||
gotenberg:
|
||||
image: gotenberg:1.0.0
|
||||
labels:
|
||||
- traefik.backend=gotenberg
|
||||
- traefik.frontend.rule=Host:gotenberg.yourdomain.com
|
||||
- traefik.port=3000
|
||||
```
|
||||
|
||||
You may now launch your services using:
|
||||
|
||||
```sh
|
||||
docker-compose up --scale gotenberg=your_number_of_instances
|
||||
```
|
||||
|
||||
When requesting `gotenberg.yourdomain.com` with your client(s), Traefik will automatically redirect a request to a Gotenberg container
|
||||
according to the load-balancing strategy you have defined.
|
||||
|
||||
## Custom implementation
|
||||
|
||||
## Scalability
|
||||
The API relies on a simple YAML configuration file called `gotenberg.yml`. It allows you to tweak some values and even provides you
|
||||
a way to change the commands called for each kind of conversion.
|
||||
|
||||
The default configuration is located here: [.ci/gotenberg.yml](.ci/gotenberg.yml)
|
||||
|
||||
---
|
||||
|
||||
|
||||
79
README.md
79
README.md
@@ -28,24 +28,89 @@
|
||||
|
||||
# Menu
|
||||
|
||||
* [Quick start](#quick-start)
|
||||
* [API](#api)
|
||||
* [Custom implementation](#custom-implementation)
|
||||
* [Usage](#usage)
|
||||
* [Security][#security]
|
||||
* [Scalability](#scalability)
|
||||
* [Custom implementation](#custom-implementation)
|
||||
|
||||
## Quick start
|
||||
## Usage
|
||||
|
||||
Let's say you're starting the API using this simple command:
|
||||
|
||||
```sh
|
||||
$ docker run --rm -p 3000:3000 thecodingmachine/gotenberg:1.0.0
|
||||
```
|
||||
|
||||
The API is now available through `http://127.0.0.1:3000`.
|
||||
The API is now available on your host under `http://127.0.0.1:3000`.
|
||||
|
||||
## API
|
||||
It accepts `POST` requests with a `multipart/form-data` Content-Type. Your form data should provide one or more files to convert.
|
||||
It currently accepts the following:
|
||||
|
||||
* Markdown files
|
||||
* HTML files
|
||||
* Office documents (.docx, .doc, .odt, .pptx, .ppt, .odp and so on)
|
||||
* PDF files (if more than one file to convert)
|
||||
|
||||
**Heads up:** the API relies on the file extension to determine which library to use for conversion.
|
||||
|
||||
There are two use cases:
|
||||
|
||||
* If you send one file, it will convert it and return the resulting PDF.
|
||||
* If many files, it will convert them to PDF, merge the resulting PDFs into a single PDF and return it.
|
||||
|
||||
## Security
|
||||
|
||||
The API does not provide any authentication mechanisms. Make sure to not put it on a public facing port and your client(s) should always
|
||||
controls what's is sent to the API.
|
||||
|
||||
## Scalability
|
||||
|
||||
Some libraries like **unoconv** cannot perform concurrent conversions. That's why the API does only one conversion at a time.
|
||||
If your API is under heavy load, a request will take time to be processed.
|
||||
|
||||
Fortunately, you may pass through this limitation by scaling the API.
|
||||
|
||||
In the following example, I'll demonstrate how to do some vertical scaling (= on the same machine) with Docker Compose, but of course horizontal scaling works too!
|
||||
|
||||
```yaml
|
||||
version: '3'
|
||||
|
||||
services:
|
||||
|
||||
# your other services
|
||||
|
||||
gotenberg-proxy:
|
||||
# Traefik is a powerful HTTP reverse proxy which allowx us to do some load-balancing.
|
||||
# It provides various methods of load-balancing which are not described here.
|
||||
# More information: https://traefik.io/
|
||||
image: traefik:1.5-alpine
|
||||
command: --docker --logLevel=DEBUG
|
||||
volumes:
|
||||
- /var/run/docker.sock:/var/run/docker.sock:ro
|
||||
|
||||
gotenberg:
|
||||
image: gotenberg:1.0.0
|
||||
labels:
|
||||
- traefik.backend=gotenberg
|
||||
- traefik.frontend.rule=Host:gotenberg.yourdomain.com
|
||||
- traefik.port=3000
|
||||
```
|
||||
|
||||
You may now launch your services using:
|
||||
|
||||
```sh
|
||||
docker-compose up --scale gotenberg=your_number_of_instances
|
||||
```
|
||||
|
||||
When requesting `gotenberg.yourdomain.com` with your client(s), Traefik will automatically redirect a request to a Gotenberg container
|
||||
according to the load-balancing strategy you have defined.
|
||||
|
||||
## Custom implementation
|
||||
|
||||
## Scalability
|
||||
The API relies on a simple YAML configuration file called `gotenberg.yml`. It allows you to tweak some values and even provides you
|
||||
a way to change the commands called for each kind of conversion.
|
||||
|
||||
The default configuration is located here: [.ci/gotenberg.yml](.ci/gotenberg.yml)
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user