Self-hosting

Two minutes

OpenCalc runs on your own servers. Nothing phones home, there is no licence check, and no document leaves your network.

# from a clone of the repository
cp .env.example .env
# change OPENCALC_SHARED_SECRET — the file ships with a value the server refuses
docker compose up
open http://localhost:8080

The images are published, so this pulls rather than builds: casualoffice/calc is the collaboration server, casualoffice/calc-host serves the editor and keeps the documents, and casualoffice/wopi is the adapter for a host that speaks WOPI. Each is multi-arch, and each ships an SBOM and a build-provenance attestation naming the repository, workflow and commit it was built from — so what you pull can be traced to what is here. Add --build to build from your own checkout instead.

New spreadsheet → Share → send the link to somebody else. You are both editing the same sheet. Download takes away an .xlsx containing what you both typed.

What the pieces are

That split is the integration boundary, not an artefact of the demo. The collaboration server holds no per-document state and deliberately cannot mint tokens. Per join, it is told by a party that already knows: where the file lives, where the finished bytes go, who is joining and what they may do.

server/casual-calc-host is that party, written small enough to read in one sitting. When you integrate, you replace it — the collaboration server and the editor stay as they are.

Standalone or cluster

Two stacks, both docker compose up.

# one collaboration node — what most deployments should run
docker compose up                                     # :8080

# two nodes behind a proxy, coordinating through Redis
docker compose -f docker-compose.cluster.yml up       # :8090

The cluster buys horizontal capacity, not correctness. Standalone is a first-class mode and not a degraded one, which is a deliberate architectural position rather than a limitation we have not got round to.

The host contract

Four endpoints and a signature is the whole of it.

GET  /api/documents/{id}/content     # what the collaboration server fetches
POST /api/documents/{id}/callback    # where the finished bytes come back
GET  /api/documents/{id}/session     # a minted token, for the browser
GET  /api/documents/{id}/download    # what a user takes away

Implement those four against your own storage and identity, and you have replaced the reference host. Nothing else in the system needs to know.

The two addresses that get confused

They look interchangeable and are on different networks. If you do set OPENCALC_COLLAB_WS, the /collab path is added when you leave it off, because the server serves that path and nothing else — an endpoint without it is an address nothing answers.

Tokens and identity

Your host mints a short-lived JWT per join; the collaboration server verifies it and cannot produce one. The claims are the whole contract: who the user is, which document, where its bytes live, where to post them back, and what this person may do.

Access is view, comment or edit, and it is enforced at the operation, on the server. A client that hides its toolbar and a server that enforces nothing look identical until somebody edits anyway.

Host variables

Collaboration variables

The ones an operator actually changes:

WOPI variables

Changing things while it runs

/admin is off entirely unless OPENCALC_ADMIN_TOKEN is set. There is no default password — a demo that ships with a known one is a demo somebody exposes to the internet once and then explains.

It changes what can safely move under a live server: the endpoint new sessions are given, whether uploads are offered, the banner. Settings are written beside the documents, so they survive a restart.

Fonts

Only the headless renderer needs these — thumbnails and PNG export. The editor never does; the browser draws cells with its own faces.

Latin is built in. Drop a .ttf, .otf or .ttc into OPENCALC_FONT_DIR for any other script and it is registered at boot. Empty is fine and is the normal case.

Behind a reverse proxy

Working configurations for nginx and Caddy are in deploy/. Two things are not obvious, and each produces the same symptom — an editor that reconnects forever:

1. The WebSocket upgrade headers

   Without Upgrade and Connection, the handshake is answered with a plain 200.

2. A read timeout longer than the server's client ping

   A co-editing socket is idle whenever nobody is typing, and nginx closes idle proxied connections after sixty seconds by default. The server should decide when a participant has gone; the proxy deciding for it looks like a network fault to everybody in the document.

Serve everything from one origin — editor, API and WebSocket. A share link is then a single URL, with no CORS to configure and no second certificate. The standalone stack does this itself: docker compose up starts an nginx in front of both services, so the page and the socket share a hostname.

TLS

Terminate at your proxy, which is what most deployments already do, and forward X-Forwarded-Proto so the host hands out wss:// rather than ws://. An https page cannot open a ws:// socket at all, and the browser's refusal is the only thing that reports it.

If you would rather the collaboration server terminate TLS itself, point OPENCALC_TLS_CERT at a certificate and key. Set OPENCALC_TRUSTED_PROXIES to the proxies whose forwarding headers you are willing to believe — believing anybody's lets a client choose its own apparent address.

Health and metrics

The counters worth putting on a dashboard:

Storage and backup

The reference host keeps each document and its metadata as files under OPENCALC_STORE, which compose mounts as a named volume. Back that directory up and you have backed up every document.

When you replace the reference host with your own, this stops being ours: storage, retention and backup become whatever your product already does. That is the point of the boundary.

The reference host keeps the previous contents of a document each time it is saved, bounded by OPENCALC_MAX_VERSIONS (default 20). They are listed, downloadable and restorable:

GET  /api/documents/{id}/versions             # newest first
GET  /api/documents/{id}/versions/{at}        # look at one
POST /api/documents/{id}/versions/{at}/restore

Restoring keeps the current document as a version first, so a restore is itself undoable — the one button whose purpose is undoing a mistake should not be the only one that cannot be undone.

When you replace the reference host with your own, this stops being ours: retention and restore become whatever your product already does, and the callback is where each finished version arrives.

Sizing and performance

Measured, not modelled — and labelled where the two differ.

What the engine costs, per operation

The adversarial recalc case is the one that matters: a deep dependency chain and a wide fan-out, which is the shape a worst case takes. At 3.1 ms against a 50 ms cap, recalculation is not close to being the limit.

What a sheet costs in memory

83.64 bytes per cell, measured as the peak resident-set delta for a 50 000-cell build on the CI runner.

What a live document costs on the server

The per-cell figure above is the workbook. A document that is open costs more than its cells: an operation log, participant state, and the broadcast path to everyone in it. That overhead is now measured — 190 KB per open document at three editors — from a sweep against a Linux container, with the node reporting its own resident set.

Every edit was acknowledged at every step — 10 200 of 10 200. The per-document column falls as documents are added because it still carries a share of the 6.6 MB a node costs when empty; the marginal cost between the 25- and 50-document runs is 143 KB. Round to 190 KB and it is a safe number to size with.

Latency is a Docker Desktop VM on a laptop, so treat p99 as an upper bound rather than a specification — it did not degrade between 50 and 150 concurrent editors, which is the part that matters. RSS is the figure to trust: it is read from the node's own opencalc_resident_bytes gauge inside the container.

Nodes, sheets and people

At three concurrent editors per sheet, and with the default OPENCALC_MAX_DOCUMENTS of 1 000 per node:

Nothing here is a configured ceiling. There is no cap on documents or on people; a node admits work until its memory is short, and the figures above are what that works out to. It scales by adding nodes — a document is owned by exactly one node at a time, so nodes do not contend for it.

A rule of thumb

If you want one line to size a node from, this is it:

# RAM for documents, in GB
GB  =  users ÷ 3  ×  (average cells per sheet × 84 bytes  +  190 KB)  ×  1.2

# or, backwards — how many people a node holds
users  =  GB × 3 ÷ ((average cells × 84 bytes + 190 KB) × 1.2)

÷ 3 is the editors-per-sheet assumption — change it to yours. 84 bytes is the measured per-cell cost and 190 KB the measured per-document one; both are figures this project ran for, not estimates. ×1.2 is what is left of the headroom once the overhead is a term rather than a guess — it covers the 85% admission mark and nothing else. The previous form of this line multiplied cells alone by a generous ×1.4 to stand in for an unmeasured overhead, and that stand-in was too small by 3× for small documents. Add the 190 KB; do not fold it into a fudge.

Worked ranges

At three editors a sheet, sized with the headroom above. Pick the row that matches your documents, not your ambitions — sheet size moves this far more than user count does.

Add nodes rather than growing one past about 16 GB. A document is owned by exactly one node, so capacity adds up cleanly, and one large node is a single thing to lose.

The engine is not what runs out first

Worth stating plainly, because it is where sizing intuition usually goes wrong. Three thousand editors each committing two edits a second is 6 000 edits a second; at 0.25 µs of engine time each, that is 1.5 ms of CPU per wall second — about a sixth of one percent of a single core.

What you will actually run out of is memory, and then socket and broadcast work. Provision for resident documents and connection count, not for calculation.

Nextcloud, SharePoint, Moodle, ownCloud, Alfresco

The WOPI adapter is what makes OpenCalc installable into a file store: an administrator pastes one URL into their settings and OpenCalc appears in the editor list.

docker compose --profile wopi up -d
# then give your file store:
https://your-host/hosting/discovery

A file opened that way is fetched from the store, edited — with everybody who opens it in the same session — and written back under its own name, in the format it arrived in. .xlsx, .csv, .tsv and .psv round-trip today. .ods does not yet, and is deliberately absent from the advertised list rather than accepted and silently converted.

Failures worth knowing about first

What is not done yet

• No Helm chart or Kubernetes manifests. Compose is the supported path today.
• Redis in the cluster stack is a single unreplicated instance. Fine for capacity, not yet an availability story.
• Secrets are environment variables and mounted files — there is no integration with a secret manager yet.

These are tracked in the open, not hidden: the execution tracker lists every one with its priority.

The operator's reference is docs/65, the WOPI handshake is in docs/74, and every variable's authoritative default is the main.rs of the binary that reads it — the only copy that cannot go stale.