mirror of
https://github.com/shumaiOne/shumai.git
synced 2026-11-22 23:38:42 +00:00
107 lines
4.3 KiB
Plaintext
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.
|