Skip to main content
Collabase runs on a single server by default — the application, database, queue, document processor, collaboration relay, and reverse proxy all on one machine. This page explains how to size that server for your team, and how to move parts of it onto separate machines when one server is no longer enough.

What drives resource use

Three different numbers matter, and they are easy to confuse: Size for peak concurrent activity, not for the total member count.

Sizing a single server

Choose your edition and the number of users to see what we recommend for production. The calculator recommends by licence and user count. The table below sizes by people working at the same moment, which is what the load depends on. Use it to fine-tune the recommendation. These are starting points for the default single-server install. Begin here, then adjust from what monitoring actually shows — a document-heavy team with constant PDF exports needs more than a team that mostly reads.
The 4 GB minimum assumes live collaboration is on. Turning it off removes the relay and brings the floor back to 2 GB for a small install.
Disk grows with uploaded files, the database, and daily backups. Watch it and expand the volume before it fills — see Disk usage.

Scaling beyond one server

When a single server can no longer keep up — sustained high CPU, memory pressure that a bigger box would only postpone, or a need for redundancy — spread Collabase across machines. Do it in this order; each step removes one reason the application server has to be big. Horizontal scaling — multiple application replicas — is available on the Kubernetes (Helm) and Docker Swarm deployments. The single-server Docker install scales up (a bigger machine), not out.

Move uploads to object storage

Point file storage at an S3-compatible bucket instead of the local disk. Uploads then live in the bucket, not on the server, so the application server needs almost no data disk and any number of replicas share the same files. Set STORAGE_DRIVER=s3 (Docker) or storage.driver: s3 (Helm) — full steps are in File storage. Object storage is also a prerequisite for running more than one application replica: replicas must not each hold their own copy of uploads.

Move the database to its own server

Run PostgreSQL on a dedicated or managed server and point Collabase at it. This frees the application server’s memory and CPU for serving requests, and lets you size and back up the database independently.
  • Kubernetes: set postgresql.enabled: false and postgresql.externalUrl to your database’s connection string.
  • Docker Swarm: point DATABASE_URL at the external database and remove the in-stack Postgres service.
The database must be PostgreSQL 16+ with the pgvector extension (used by AI search).

Run multiple application replicas

With uploads on S3 and the database external, the application server is stateless and can run as several identical replicas behind the reverse proxy, sharing the load and surviving the loss of any one.
1

Meet the prerequisites

Object storage (storage.driver: s3) and — so background jobs run in exactly one place — a dedicated worker. On Helm, set workers.separate: true.
2

Raise the replica count

On Helm, set replicaCount to the number of application instances you want. Swarm uses the service’s replicas setting. The chart refuses replicaCount > 1 without object storage, because local uploads cannot be shared.

Size a Kubernetes installation

Use this section to choose node sizes and the limits of each workload for the Helm chart. Every number carries its source: measured in a test cluster, extrapolated linearly from a measurement, or assumption. The measurements used concurrently active people with think time, calling the API only: reading, searching, creating work items, setting priority and status, commenting. Ten projects, demo data. Live editing, AI, attachments and exports were not part of the load, so leave headroom if your team uses them heavily.

What was measured

The test cluster had two nodes with 4 vCPU and 8 GB each, about 5.6 GiB usable per node. The bottleneck is the CPU of the app, then memory. The database used 0.3 to 0.4 cores. One app core carries about 100 concurrently active people (extrapolated from 200 people at about 2 cores).

Requests and limits per workload

The first columns are the defaults of the chart, from values.yaml. The last columns are an example for two nodes with 4 vCPU and 16 GB each, about 13.5 GiB usable per node (assumption), running three app instances. The example values are not defaults, and they were derived from the rules on this page, not measured on these nodes. The chart gives the worker the values of the app. A smaller worker, as in the example, needs a post-renderer, see Scheduling and platform settings. A second database instance for high availability is not part of the chart. Use an external PostgreSQL with failover, see Use your own database. With the example values, the memory limits of all workloads add up to 26.5 GiB, against about 27 GiB usable on both nodes. During an update one more app instance runs, which brings the limits to 29.5 GiB. That is about 1.1 times the usable memory. We accept this on purpose: a limit is a ceiling, and normal use stays far below it, see the measurements above. The risk is a pod that is stopped for memory (exit code 137) if the surge pod and all others peak at the same time.
The sum of all memory limits must stay below the usable memory of your nodes, apart from the short overbooking of an update. In a test, limits that exceeded the node memory 2.2 to 2.6 times stopped pods with exit code 137 (measured).

How many people the example carries

Of the 8 vCPU in the example, about 0.8 go to the kubelet and the network agents, 1 to the database and 1 to the worker, queue, relay, sandbox and document processor on average. About 5 cores remain for the app (extrapolated). Both nodes have the same CPU as the test cluster, only more memory, so the number of people depends on CPU, not on memory. An additional node with 4 vCPU raises the CPU of the app by about 3 cores, roughly 300 more people (extrapolated).

Database connections

The chart gives each app process 80 % of postgresql.tuning.max_connections, divided by the number of app processes (instances plus the dedicated worker), at most 100 each. It does not count the extra instance that runs during a rolling update. Set database.connectionLimit yourself so that the total stays below the database limit. For example, with max_connections: "400", three app instances and one worker, the chart gives 80 connections to each of the four processes. With the extra instance of an update there are five processes, so set database.connectionLimit: 64 (320 divided by 5). Each connection costs the database about 5 to 10 MiB (assumption), so raise max_connections together with the memory of the database.

Many people creating in one project

Work items of a project take their numbers from one counter. Hundreds of people who create in the same project at the same moment wait for each other. In the test, 200 people in one project reached a 95th percentile of 10 s and 2.4 % errors, against 0.63 s when they were spread over ten projects (measured). Adding nodes does not change this. Spread busy teams over several projects.

The collaboration relay at scale

The relay is a single process and handles a large number of connections across all documents on one instance — no cluster and no Redis are needed for typical deployments. The practical ceiling is per document: a page with dozens of simultaneous editors is fine, and only very large single-page sessions (around a hundred people editing one page at once) reach the point where cursor traffic dominates. If you ever need to run more than one relay instance for redundancy or extreme scale, that requires a shared Redis for the relay to coordinate — a setup worth a scaling consultation rather than a default.
Last modified on November 13, 2026