> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flowx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Document Converter setup

> Configure the Document Converter service that converts Office documents, images, and text into PDF for downstream parsing.

The Document Converter (`doc-converter`) is a lightweight service that converts source files into PDF. It normalizes Office documents, images, and plain text into a single format the [Document Parser](./document-parser-setup) and other AI workflows can process. It is a separate service from the Document Parser.

<Info>
  The Document Converter is **CPU-only** — it loads no ML models and does not use a GPU. Conversion runs through headless LibreOffice and image libraries.
</Info>

## Dependencies

The Document Converter connects to standard FlowX infrastructure services that should already be configured in your environment:

* [**Kafka**](/5.9/setup-guides/kafka-authentication-config) — event-driven conversion of files stored in object storage
* **Object storage** (S3-compatible / MinIO) — source and result files for the object-conversion endpoint and Kafka mode
* [**CMS Core**](/5.9/setup-guides/cms-setup) — file retrieval from FlowX content management

## Capabilities

The service converts the following input formats to PDF:

| Input            | Extensions                                                                        | Conversion                                     |
| ---------------- | --------------------------------------------------------------------------------- | ---------------------------------------------- |
| Office documents | `.doc`, `.docx`, `.xls`, `.xlsx`, `.ppt`, `.pptx`, `.odt`, `.ods`, `.odp`, `.rtf` | Headless LibreOffice                           |
| Images           | `.png`, `.jpg`, `.jpeg`, `.tif`, `.tiff`, `.webp`, `.gif`                         | Placed on an A4 canvas, aspect ratio preserved |
| Text             | `.txt`                                                                            | Rendered to PDF                                |
| PDF              | `.pdf`                                                                            | Passed through unchanged                       |

The service runs in two modes:

* **HTTP API** — synchronous conversion of an uploaded file or a file in storage
* **Kafka consumer** — event-driven conversion of files stored in object storage

***

## API endpoints

All endpoints are prefixed with the `URL_PREFIX` value (default: `/doc-converter`).

| Endpoint                               | Method | Purpose                                         |
| -------------------------------------- | ------ | ----------------------------------------------- |
| `/api/v1/doc-converter/convert/file`   | POST   | Convert an uploaded file to PDF                 |
| `/api/v1/doc-converter/convert/object` | POST   | Convert a file from CMS/object storage to PDF   |
| `/api/v1/doc-converter/image/file`     | POST   | Convert an uploaded image to PDF                |
| `/api/v1/doc-converter/image/object`   | POST   | Convert an image from CMS/object storage to PDF |
| `/api/v1/doc-converter/info/health`    | GET    | Health check                                    |

***

## Configuration

### Server configuration

| Environment Variable | Description                                 | Default Value    |
| -------------------- | ------------------------------------------- | ---------------- |
| `URL_PREFIX`         | FastAPI root path for reverse proxy routing | `/doc-converter` |
| `MAX_UPLOAD_MB`      | Maximum upload size per request, in MB      | `100`            |
| `VERBOSE`            | Enable verbose/debug logging                | `0`              |

The service listens on port `8080`.

### Image conversion

| Environment Variable | Description                                                    | Default Value            |
| -------------------- | -------------------------------------------------------------- | ------------------------ |
| `IMAGE_MAX_PIXELS`   | Maximum pixel count for an input image before it is downscaled | `14960000` (3400 × 4400) |
| `IMAGE_JPEG_QUALITY` | JPEG quality used when normalizing images                      | `80`                     |

### Object storage

Required for the object-conversion endpoints and the Kafka consumer, which read and write files in S3-compatible storage.

| Environment Variable         | Description                                 | Default Value |
| ---------------------------- | ------------------------------------------- | ------------- |
| `MINIO_DOCUMENTS_URL`        | Object storage endpoint URL                 | `none`        |
| `MINIO_DOCUMENTS_BUCKET`     | Bucket for source and result files          | `none`        |
| `MINIO_DOCUMENTS_ACCESS_KEY` | Object storage access key                   | `none`        |
| `MINIO_DOCUMENTS_SECRET_KEY` | Object storage secret key                   | `none`        |
| `CMS_USE_PRIVATE`            | Retrieve files through the private CMS path | `1`           |

<Info>
  The Kafka consumer is enabled by default. Configure Kafka connection and authentication as described in the [Kafka authentication configuration](/5.9/setup-guides/kafka-authentication-config) guide. CORS for the HTTP endpoints is configured through the standard `APPLICATION_CORS_ALLOW_*` variables — see the [Ingress configuration](/5.9/setup-guides/ingress-configuration) guide.
</Info>

### Observability (optional)

| Environment Variable        | Description                         | Default Value |
| --------------------------- | ----------------------------------- | ------------- |
| `USE_OBSERVATORY`           | Send telemetry to FlowX Observatory | `0`           |
| `FLOWX_OBSERVATORY_API_URL` | FlowX Observatory API URL           | -             |

***

## Deployment and sizing

The Document Converter is a lightweight, **CPU-only** service — it needs no GPU. Conversions run as short-lived LibreOffice subprocesses, so memory is the main resource to size for; large Office documents can briefly increase memory use.

| Setting             | Value                                       |
| ------------------- | ------------------------------------------- |
| Replicas            | 1 (default)                                 |
| Autoscaling         | Min 1, Max 5, HPA target CPU 50%            |
| RAM requests/limits | \~1 Gi (FlowX Cloud production runs 896 Mi) |
| GPU                 | None                                        |

<Tip>
  Increase the memory limit if you convert large or complex Office documents. Scale horizontally with more replicas for higher conversion throughput.
</Tip>

***

## Verify your setup

<Check>
  The Document Converter pod is running: `kubectl get pods -l app=doc-converter`
</Check>

<Check>
  The health endpoint returns HTTP 200: `curl http://doc-converter:8080/api/v1/doc-converter/info/health`
</Check>

<Check>
  Test a conversion against the `/api/v1/doc-converter/convert/file` endpoint and verify the response is a PDF.
</Check>

***

## Related resources

<CardGroup cols={2}>
  <Card title="Document Parser setup" icon="file-magnifying-glass" href="./document-parser-setup">
    Configure the Document Parser for text extraction and OCR
  </Card>

  <Card title="AI Platform setup" icon="server" href="./ai-platform-setup">
    Configure AI Platform services and service discovery
  </Card>

  <Card title="Kafka authentication" icon="key" href="./kafka-authentication-config">
    Configure Kafka connection and authentication
  </Card>

  <Card title="CMS Core setup" icon="database" href="./cms-setup">
    Configure content management for file retrieval
  </Card>
</CardGroup>