Files
shumai/docs/using-shumai/gotenberg.mdx
T

107 lines
4.3 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
Shumai supports configuring Gotenberg either through the **WebUI** or via **Environment Variables**.
### 1. WebUI (Team Settings → Integrations)
Team owners can configure Gotenberg directly from the web interface:
1. Navigate to **Team Settings** from the sidebar.
2. Select the **Integrations** tab.
3. Under **Gotenberg Document Converter**, enter the **Server URL** (e.g. `http://gotenberg:3000` or `http://localhost:3000`).
4. Enter the **Username** and **Password** if Basic Authentication is enabled on the service.
5. Click **Test Connection** to test communication with Gotenberg and verify its health.
6. Click **Save Changes**.
### 2. Environment Variables
Gotenberg can also be configured globally across the system using environment variables on the machine running Shumai or 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. |
### Configuration Priority & Read-Only Mode
> [!IMPORTANT]
> **Environment variables take highest priority.** If `GOTENBERG_URL` is set in your environment, Shumai will always use the environment variable configuration.
>
> When configured via environment variables, the settings in **Team Settings → Integrations** will display a **Configured via environment variables (Read-only)** badge, and the input fields will be locked to prevent accidental changes or configuration drift.
### Deploying 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.