mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 20:37:40 +00:00
83 lines
3.1 KiB
Plaintext
83 lines
3.1 KiB
Plaintext
---
|
|
title: Document PDF Conversion with Gotenberg
|
|
description: Convert Office documents, HTML, Markdown, CSV, and TXT files into high-fidelity PDF proxies for in-browser previewing.
|
|
---
|
|
|
|
Office documents, HTML pages, Markdown files, spreadsheets, and plain-text files cannot be rendered natively in web browsers. Shumai uses [Gotenberg](https://gotenberg.dev), an open-source, Docker powered conversion API — to turn these files into PDF proxy assets for seamless in-browser previewing.
|
|
|
|
Gotenberg performs the conversion using:
|
|
|
|
- **LibreOffice** for Office documents, spreadsheets, and plain text.
|
|
- **Headless Chromium** for HTML and Markdown files.
|
|
|
|
---
|
|
|
|
## Supported File Types
|
|
|
|
When Gotenberg is configured, Shumai automatically generates a PDF proxy for the following uploads:
|
|
|
|
| Category | Extensions | Converter |
|
|
| ------------------ | ---------------------- | ----------- |
|
|
| Word | `.doc`, `.docx` | LibreOffice |
|
|
| Excel | `.xls`, `.xlsx` | LibreOffice |
|
|
| PowerPoint | `.ppt`, `.pptx` | LibreOffice |
|
|
| OpenDocument | `.odt`, `.ods`, `.odp` | LibreOffice |
|
|
| Rich Text | `.rtf` | LibreOffice |
|
|
| HTML | `.html`, `.htm` | Chromium |
|
|
| Markdown | `.md`, `.markdown` | Chromium |
|
|
| Spreadsheets / CSV | `.csv` | LibreOffice |
|
|
| Plain text | `.txt` | LibreOffice |
|
|
|
|
---
|
|
|
|
## Configuration
|
|
|
|
Gotenberg support is opt-in and controlled by the following environment variables on the machine running the transcode workers:
|
|
|
|
| Variable | Required | Description |
|
|
| ------------------------------- | --------------- | ---------------------------------------------------------------- |
|
|
| `GOTENBERG_URL` | Yes (to enable) | Base URL of the Gotenberg service, e.g. `http://gotenberg:3000`. |
|
|
| `GOTENBERG_BASIC_AUTH_USERNAME` | No | Username when Basic Authentication is enabled on Gotenberg. |
|
|
| `GOTENBERG_BASIC_AUTH_PASSWORD` | No | Password when Basic Authentication is enabled on Gotenberg. |
|
|
|
|
### Docker Quickstart
|
|
|
|
You can start a Gotenberg container with a single command:
|
|
|
|
```bash
|
|
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8
|
|
```
|
|
|
|
If you wish to enable Basic Authentication:
|
|
|
|
```bash
|
|
docker run -d --name gotenberg -p 3000:3000 gotenberg/gotenberg:8 gotenberg --gotenberg-basic-auth-username=admin --gotenberg-basic-auth-password=secret
|
|
```
|
|
|
|
### Docker Compose Setup
|
|
|
|
Add a Gotenberg service to your `docker-compose.yaml`:
|
|
|
|
```yaml
|
|
gotenberg:
|
|
image: gotenberg/gotenberg:8
|
|
restart: unless-stopped
|
|
ports:
|
|
- '3000:3000'
|
|
```
|
|
|
|
Then point Shumai at it:
|
|
|
|
```bash
|
|
GOTENBERG_URL=http://localhost:3000
|
|
```
|
|
|
|
---
|
|
|
|
## Behavior Without Gotenberg
|
|
|
|
If Gotenberg is not configured or unreachable, Shumai degrades gracefully:
|
|
|
|
- **Office documents and HTML**: the upload completes as `processed` without a PDF proxy.
|
|
- **CSV, Markdown, and TXT**: a lightweight built-in PDF generator produces the proxy instead, with reduced fidelity.
|