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 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	.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

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

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

---

Verify your setup

The Document Converter pod is running: kubectl get pods -l app=doc-converter

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

Test 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