Office conversion (Collabora CODE)

Module id: office_convert · Kind: sidecar · Configured by: OFFICE_CONVERT_URL · Capability: pdf_export

Everything Synaplan does with an Office file beyond reading its text — thumbnails, "Download as PDF", inline preview, combining several files into one PDF — needs a real office engine. That engine is a Collabora CODE container (LibreOffice, headless) reached over its convert-to API. Off by default; enabled with one Compose profile.

The long-form guide with every deployment variant is Office documents. This page is the short module view.

What it adds

  • Thumbnails for .docx, .xlsx, .pptx and friends in the file list.
  • Download as PDF for any Office file; PDF output for generated documents (officemaker).
  • Inline preview of Office files in the browser.
  • Legacy format conversion (.doc, .xls, .ppt, …) before analysis.
  • Combine as PDF across mixed formats (Word + Excel + PDF into one document).
  • The office_convert step of the Documents extraction chain and the pdf_export capability the assistant can use in multi-task plans.

Without it

Office files still upload, extract and search — text comes from Tika and the structured Office reader. What is missing is the visual side: no thumbnails, no PDF export, no preview; Combine still works for inputs that already share one format. The routes stay reachable and degrade per request, so nothing 404s because the engine is absent. Installing LibreOffice on the host with apt is not a substitute — the backend talks to the engine over HTTP, and the host binary is not visible inside the container.

How to enable

Developer / evaluation stack

COMPOSE_PROFILES=office docker compose up -d      # or: docker compose --profile office up -d

The Compose file defaults OFFICE_CONVERT_URL to http://collabora:9980, so nothing else is needed. Expect about 2 GB of extra RAM for the container.

Production (deploy/compose.yaml)

Add the profile to deploy/.env and redeploy:

COMPOSE_PROFILES=office        # comma-separate if you also run local-ai: local-ai,office

The app's start wrapper exports OFFICE_CONVERT_URL=http://collabora:9980 whenever office is in the profile list, so the variable never has to be set by hand for the bundled engine.

An existing Collabora (Nextcloud, OpenCloud, another stack)

Point the backend at it and restart backend + worker:

OFFICE_CONVERT_URL=https://collabora.example.com
OFFICE_CONVERT_TIMEOUT_MS=60000

Synaplan only calls the anonymous convert-to endpoint — Collabora never sees a Synaplan user or document permission, and no WOPI host is required. See Office documents → Using an existing Collabora.

Turning it off deliberately

OFFICE_CONVERT_URL=disabled

Check it works

  • Operate → Feature Status → Office conversion shows Available / Office converter is running. The probe is GET /hosting/capabilities on the engine.
  • GET /api/v1/config/runtime reports features.officeConvertEnabled: true and modules.office_convert.configured: true.
  • Upload a .docx: a thumbnail appears within a few seconds and the file menu offers Download as PDF.

Configuration reference

Variable Default Meaning
OFFICE_CONVERT_URL empty (dev Compose: http://collabora:9980) Base URL of the Collabora / CODE engine. Empty or disabled = module off.
OFFICE_CONVERT_TIMEOUT_MS 60000 Per-conversion timeout. Large spreadsheets and decks may need more.

Related, not module-owned: OFFICE_TEXT_MAX_ROWS (rows read from spreadsheets for text) and OFFICE_COMBINE_MAX_FILES (inputs per combine job).

Troubleshooting

  • Office converter is not reachable. The container needs a moment after start; docker compose logs collabora. Behind a reverse proxy make sure /hosting/capabilities and /cool/convert-to/... are forwarded.
  • Thumbnails missing only for old .doc files. They are converted first; raise OFFICE_CONVERT_TIMEOUT_MS if the log shows timeouts.
  • Kubernetes. The Helm charts ship an optional Collabora deployment — see Office documents → Kubernetes.

Related