Office documents

Synaplan can create, analyse, convert, preview and merge Word, Excel, PowerPoint and PDF files. The extra capabilities — thumbnails, Download as PDF, inline preview, officemaker PDF output, legacy/Apple format conversion, and combining several files into one PDF — need a LibreOffice engine next to the app.

That engine is Collabora Online (collabora/code), a LibreOffice-based sidecar reached over HTTP (OFFICE_CONVERT_URL). It is optional. Without it, chat, Tika RAG and today's officemaker (DOCX / XLSX / PPTX via PhpOffice) keep working. The capabilities below stay off.

This is not the same as installing LibreOffice on the host, and not the same as Desktop's local LibreOffice (used by Agent Skills on the user's computer).

What requires the engine

When the engine is off, the app behaves as it did before these features existed. Self-hosters lose nothing they have today.

Identification — Collabora never sees your users

Convert-to is a server-to-server HTTP call. Synaplan POSTs a file to {OFFICE_CONVERT_URL}/cool/convert-to/<format> (multipart field data) and stores the bytes next to the source.

Collabora does not receive:

• a Synaplan login, session, or API key
• a user id, email, or display name
• a WOPI token or Collabora account

Who may see or change a file is decided only in Synaplan: the signed-in user, file ownership, and (when document tools are on) revision rows. Collabora is a stateless converter. You do not create Collabora users for Synaplan users, and you do not map Nextcloud / OpenCloud WOPI identities onto this path.

The later editor (WOPI) will still not create Collabora accounts. Synaplan will be the WOPI host and will send a short-lived, file-scoped token plus OwnerId / UserId / UserFriendlyName. That is not shipped yet.

How to enable (development)

The sidecar is behind the compose profile office, so a plain docker compose up -d does not pull the image or spend the extra ~2 GB RAM. Local compose defaults OFFICE_CONVERT_URL to http://collabora:9980 — you do not put that URL in backend/.env (Compose already injects the variable, so the file cannot override it).

cd synaplan
docker compose --profile office up -d

This pulls collabora/code (about 1–2 GB RAM, compose mem_limit 2g) and starts it on the compose network. There is no published convert-to port — only the backend and worker talk to collabora:9980.

Verify as an administrator:

curl -s http://localhost:8000/api/v1/config/runtime
# features.officeConvertEnabled should be true

curl -s http://localhost:8000/api/v1/config/features
# the office-convert entry should report the sidecar as available

Turn the engine off even when the compose default would enable it:

OFFICE_CONVERT_URL=disabled docker compose up -d

How to enable (self-host / deploy/compose.yaml)

Deployments use environment variables, not backend/.env. The portable production file keeps OFFICE_CONVERT_URL empty unless you opt in, so the official 8 GB RAM floor stays valid.

Start the bundled sidecar:

# in deploy/.env
COMPOSE_PROFILES=office

or:

docker compose --env-file deploy/.env -f deploy/compose.yaml --profile office up -d

The deploy entrypoint sets OFFICE_CONVERT_URL=http://collabora:9980 when office is listed in COMPOSE_PROFILES. Same sidecar, no public convert-to port.

Point at an existing CODE instance instead (do not also start the office profile if the hostname would collide):

# in deploy/.env — Compose / host env, not backend/.env
OFFICE_CONVERT_URL=http://<existing-collabora-host>:9980

Umbrel, AWS Marketplace and Elestio images keep the engine off (small VMs cannot spare ~2 GB).

Using an existing Collabora (Nextcloud, OpenCloud, another compose)

An already-running CODE works for convert-to if:

1. The Synaplan backend and worker (and, on a multi-worker host, the bulk worker) can reach the URL.
2. GET {url}/hosting/capabilities reports convert-to as available.
3. OFFICE_CONVERT_URL is that base URL — no /cool/... suffix.
4. You do not start Synaplan’s office profile when the DNS name collabora would hit a different container, or when container_name: synaplan-collabora would collide.

HTTPS is fine if the PHP client trusts the certificate. Nextcloud / OpenCloud WOPI users and aliasgroup are irrelevant for convert-to. Those products’ Collabora is still just an HTTP endpoint from Synaplan’s point of view.

HTTP 403 usually means CODE’s net.post_allow.host does not include the compose or cluster subnet. Add --o:net.post_allow.host[0]=<subnet regex> to that instance’s extra_params. Do not publish port 9980 for convert-to.

Hosted demo

On our hosted demo the sidecar is on by default, one container per web node (same pattern as Centrifugo — not a shared Tika or TTS box). That change lives in the private platform compose, not in this public repository.

Sizing: idle about 0.5–1 GB RAM, mem_limit 2g, --o:num_prespawn_children=2.

Kubernetes

The Helm charts do not yet ship a Collabora sidecar. Set OFFICE_CONVERT_URL on the web and worker pods (chart env:) and run CODE in the cluster or reuse an existing one. Integrator notes (identity, healthcheck, image pin, Helm examples) live in synaplan-charts docs/collabora-office-engine.md and will move to that repo’s default branch when the chart grows a sidecar.

See also Kubernetes.

Host apt install libreoffice is not enough

The PHP app runs in Docker and cannot execute host binaries. Ubuntu libreoffice-* packages on a server are unused by the containers. Do not bind-mount /usr/bin/soffice into the backend image.

The only supported path is Collabora CODE and OFFICE_CONVERT_URL.

Not the same as Desktop LibreOffice

Check this computer looks for LibreOffice on the user's PC so Agent Skills can export slides and PDFs locally. Server-side office features need the Collabora sidecar on the Synaplan host. Both can be installed; they do not replace each other.

Related

• Quickstart & Self-Hosting — optional profile and pitfalls
• Production — deploy/ contract and RAM floor
• Architecture — service map
• Using Synaplan — Files & RAG
• Text-to-Speech — another optional companion (different topology)