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 and other AI workflows can process. It is a separate service from the Document Parser.
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.
Dependencies
The Document Converter connects to standard FlowX infrastructure services that should already be configured in your environment:- Kafka — 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 — 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 | Passed through unchanged |
- 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 theURL_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 |
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 |
The Kafka consumer is enabled by default. Configure Kafka connection and authentication as described in the Kafka authentication configuration guide. CORS for the HTTP endpoints is configured through the standard
APPLICATION_CORS_ALLOW_* variables — see the Ingress configuration guide.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 |
Verify your setup
The Document Converter pod is running:
kubectl get pods -l app=doc-converterThe health endpoint returns HTTP 200:
curl http://doc-converter:8080/api/v1/doc-converter/info/healthTest a conversion against the
/api/v1/doc-converter/convert/file endpoint and verify the response is a PDF.Related resources
Document Parser setup
Configure the Document Parser for text extraction and OCR
AI Platform setup
Configure AI Platform services and service discovery
Kafka authentication
Configure Kafka connection and authentication
CMS Core setup
Configure content management for file retrieval