Architecture and components Beta

Version 1 favours few moving parts and reliability: o3o-gate and DocBuilder are written in Python, the DocBuilder queue lives in memory and each service is one container. No O3O code is patched into the editing server; the services talk to each other over HTTP and WebSocket.

Services#

Proxy routing#

Opening a document through Nextcloud#

1. The administrator installs the richdocuments connector app, then runs richdocuments:activate-config with -w http://o3o-online:9980 (the address Nextcloud uses to reach the editing server) and -c http://o3o-nextcloud (the address the editing server uses to call Nextcloud back, which becomes the origin of WOPISrc). Nextcloud reads /hosting/discovery to learn the editor page path.
2. A user clicks a file. Nextcloud builds an iframe and posts a form to cool.html with WOPISrc and access_token.
3. The proxy asks o3o-gate: if there is room the editor loads; if not the user sees the limit page with buttons to open read-only or retry.
4. The editor opens a WebSocket; the proxy asks o3o-gate again at the ws stage.
5. The editing server calls Nextcloud back over WOPI: CheckFileInfo, GetFile, and PutFile on save. o3o-gate is not on the save path, so it can never block a save.

Direct embedding flow#

1. Your page loads /o3o/api.js and calls new O3O.Editor(id, config).
2. api.js sends POST /o3o/embed/session. o3o-gate checks the origin and the JWT, downloads document.url under the SSRF rules, applies the connection cap and returns the editor address and an access_token.
3. api.js builds the iframe and posts the form; WOPISrc points at o3o-gate's internal WOPI host.
4. The editing server calls o3o-gate over the internal network to read and write the file. On each save o3o-gate stores a new version, answers immediately, then sends an HMAC-signed callback to callbackUrl.
5. The browser receives events through postMessage. When everyone has left the document for 30 seconds, o3o-gate sends a closed callback and keeps the file for 24 hours.

DocBuilder flow#

1. Your server calls /v1/convert, /v1/build, /v1/template/render or /v1/extract/* with Authorization: Bearer.
2. DocBuilder authenticates, resolves the plan from the license token, applies the rate limit, validates the parameters (o3oscript scripts against the JSON Schema), downloads the source URL if any, then queues the job in memory.
3. An idle worker (a dedicated headless LibreOffice process) runs the job. Macros never run: files loaded through LibreOffice always have macros disabled, and /v1/template/render rejects templates that contain macros with 422 macro_not_allowed. On timeout the worker is stopped and rebuilt and the job fails with timeout.
4. Synchronous mode returns the file directly. Asynchronous mode returns 202 with a job; poll GET /v1/jobs/{id} and download from GET /v1/files/{id}.

Connection counting#

One connection is one concurrent editing session. One person with 3 documents open for editing is 3 connections; three people editing one document are 3 connections. o3o-gate samples editing sessions every 10 seconds from the editing server's internal admin channel, reports a 5-minute sliding peak for reconciliation and allows reconnection within 120 seconds even at the cap.

• Open sessions are never cut off, even when the cap is lowered (expired or replaced token).
• Saves are never blocked: o3o-gate is not on Nextcloud's save path, and embedded saves ignore the cap.
• At the cap: new sessions through Nextcloud see the limit page; new embedded sessions open read-only with a notice banner.
• Counting errors or an unresponsive editing server: o3o-gate lets traffic through (fail-open) and logs it. If o3o-gate is down entirely, nginx lets traffic through as well.
• Every 5 minutes o3o-gate appends a line to /data/usage/usage-YYYY-MM.csv so you can reconcile usage yourself.

Networks, volumes and ports#

• One bridge network, o3o-net; services reach each other by service name.
• Volumes: o3o-gate-data, o3o-docbuilder-data, o3o-nextcloud-html, o3o-nextcloud-db.
• Only two ports are published: O3O_PROXY_PORT (default 8080) and O3O_NEXTCLOUD_PORT (default 8081, only with the nextcloud profile).
• The editing server needs cap_add: [MKNOD]; its image has no shell, so debug with docker logs.

Variables to change for production#

The complete list of variables and defaults is in Self-hosting.

DEV image and release build#

Performance and hardware#

Not measured yet. The documentation gives no figures for processing time, requests per second, memory or minimum hardware per connection count; these will be published once real measurements exist on defined hardware.

Licensing#

The editing server is open source under MPL 2.0; when the source-built O3O image is released, any upstream file O3O modifies will be published to recipients of that image (coming soon). o3o-gate, api.js and the proxy configuration are standalone O3O code that talks to the editing server only over HTTP and WebSocket.

DocBuilder's own code is owned by O3O and does not modify LibreOffice code, but it is not standalone in the same way: it loads LibreOffice through the UNO bridge (python3-uno), and its image is distributed WITH LibreOffice 7.4 installed from the Debian bookworm archive, mostly under MPL 2.0 with some files under LGPL and Apache 2.0. Anyone distributing the DocBuilder image must therefore keep those packages' license notices (the image already carries /usr/share/doc/<package>/copyright) and tell recipients where to obtain the matching LibreOffice source. The obligations are detailed in the license section of Building from source.