- Multi-Tenancy Support
- Does CHT currently support a multi-tenant architecture?
- If yes, what is the recommended approach or best practice for implementing multi-tenancy within CHT?
- Are there any reference implementations or case studies available?
- Scalability and User Capacity
- What is the maximum user base that a single CHT tenant/instance can support?
- Do you have any documented benchmarks or load testing reports that outline system performance under scale?
- Are there any recommended limits regarding users, facilities, households, or data volume per instance?
Hi @Ramu
I want to make sure I’ve understood your questions correctly, but I’ll do my best.
Multi-Tenancy Support
Does CHT currently support a multi-tenant architecture?
If this means whether a single CHT server can serve multiple isolated deployments, the
answer is no. CHT is designed as one stack, one configuration, one admin scope.
A single CHT instance is a fixed set of services pointed at one CouchDB server:
- api – REST API / replication endpoint
- sentinel – background processor (transitions, scheduled messages, purging)
- couchdb – the data store (single-node or a 3+ node cluster)
- haproxy – database load balancer
- nginx – TLS termination / static assets
All organizational data lives in a handful of databases on that one CouchDB server
(the main database plus per-user metadata databases).
Recommended approach for multi-tenancy:
The standard pattern is instance-per-tenant — deploy a separate stack for each
organization. CHT ships a Helm chart designed exactly for this: each tenant is its
own Helm release with its own project name, namespace, and CouchDB. You’d run multiple
releases on a shared Kubernetes cluster.
If instead you’re after “soft multi-tenancy” — serving multiple logically-separate
groups from within a single CHT deployment — that’s only partially possible. Offline
users are already scoped by the contact hierarchy and replication depth, so you can
partition them. But online users and the API always have read access to all data
(there is no mechanism to restrict this), and there is only one shared configuration
for the whole deployment.
Scalability and User Capacity
Maximum users per instance: There’s no single “max users” number, and I’d be
skeptical of anyone who quotes one, because the real constraint isn’t user count — it’s
replication load: how many offline users sync, how many documents each replicates
(driven by hierarchy, replication depth, and report volume per contact), and total DB
size. An instance with thousands of shallow-depth CHWs behaves very differently from
one with hundreds of deep-depth supervisors. The levers for scaling are managing
per-user doc counts through smart hierarchy design, purging (and, in future, data
archiving), and the compute available to the database layer.
CHT has benchmark and load tests that we run regularly (on every release and whenever
performance-affecting changes land). Their value is comparative — detecting regressions
between runs on the same architecture — rather than simulating real-world load.
There are no official recommended limits for users/facilities/households, because
performance is almost always tied to the specifics of the data set and configuration.
There is a soft maximum on the number of documents an offline user should replicate to
their device — 10,000 — implemented in CHT core: the system warns the user at login
when they exceed it (they can still choose to continue). This threshold is fixed, not
configurable.
For concrete references and examples of the CHT scaling, there are several single-instance production deployments at national and sub-national scale. Without naming specifics, the range looks like this:
- The largest single instance serves roughly 20,000 active users a month (against ~43,000 provisioned accounts) on one database.
- Most large deployments sit in the 3,000–8,000 active-user range, with anywhere from ~4,000 to ~10,000 provisioned accounts.
- Database size scales independently of user count: across these instances the main database holds anywhere from ~7 million to ~90 million documents. The instance with the most documents (~90M) has fewer than 4,000 active users, while our highest-user instance (~20,000 users) sits around ~53M documents.
A single instance comfortably serves tens of thousands of users, and document volume — driven by hierarchy depth, reports per contact, and purging policy — matters as much as headcount when sizing a deployment.