Topology
In a Stalwart cluster, administrators control how user-facing services are distributed across nodes. This is distinct from node roles, which assign background maintenance tasks such as store maintenance or certificate renewal. Cluster topology focuses on which protocols (IMAP, JMAP, WebDAV, SMTP) each node serves.
Stalwart allows flexible service distribution: each node can be configured to handle one, several, or all supported protocols. This supports tuning for performance, resource usage, and fault tolerance according to real-world traffic patterns and operational goals.
Listener selection per node is driven by the ClusterRole object (found in the WebUI under Settings › Cluster › Roles), through its listeners field (a ClusterListenerGroup that names specific NetworkListener ids).
The sections below describe common topology strategies used in Stalwart clusters.
Unified service model
In this approach, every node handles every service: IMAP, JMAP, WebDAV, and SMTP. For example, in a 1024-node deployment, each server is configured identically and can handle any client or protocol.
This model suits:
- Simpler management with uniform configuration
- Redundancy, since any node can fail without losing service
- Smaller or mid-sized environments where traffic is evenly distributed
The unified model also simplifies load balancing and reduces operational complexity, though it may be less efficient in scenarios where some services see significantly more traffic than others.
Service-specific allocation
In this model, nodes are dedicated to specific protocols. For example, a 1024-node cluster might be divided into 256 SMTP nodes, 384 IMAP nodes, 256 JMAP nodes, and 128 WebDAV nodes.
This separation of concerns is useful when:
- Isolating workloads for performance tuning
- Certain services (for example, SMTP) need different network access or security policies
- Teams are structured around managing specific services
Service-specific allocation allows more granular resource planning, at the cost of more sophisticated monitoring and load balancing.
Weighted allocation based on load
Clusters can also be sized according to expected usage patterns. For instance, if IMAP usage is significantly heavier than JMAP or WebDAV, the topology could look like this:
| Protocol | Nodes | Rationale |
|---|---|---|
| IMAP | 512 | Long-lived connections, high memory |
| SMTP | 256 | Burst traffic, queue processing |
| JMAP | 192 | API-heavy, mobile clients |
| WebDAV | 64 | Calendar and contacts, lower volume |
This model balances redundancy and efficiency, allocating more resources to higher-demand services while still covering less-used protocols.
It suits:
- Enterprise environments with known usage trends
- Scenarios where IMAP or SMTP dominate traffic
- Clusters designed to scale incrementally
Protocol pairing model
Some organisations prefer to group complementary protocols. A common configuration looks like:
- 40 percent of the nodes for IMAP and JMAP
- 20 percent of the nodes for WebDAV
- 40 percent of the nodes for inbound and outbound SMTP
This model offers:
- Reduced configuration duplication
- Logical pairing of user-facing services (for example, IMAP and JMAP both serve mail clients)
- Efficient use of resources while still allowing role separation
Pairing services also simplifies routing and firewall policies, especially when grouped by access pattern (client-facing versus mail-routing).
Geographically distributed topology
In larger or multi-site deployments, nodes may be distributed across data centres or geographic regions, with services colocated by regional demand:
- Region A: 384 nodes (IMAP, SMTP inbound)
- Region B: 448 nodes (IMAP, JMAP, SMTP outbound)
- Region C: 192 nodes (WebDAV, JMAP, SMTP)
This approach improves:
- Latency for users in different regions
- Resilience to regional outages
- Load isolation by physical location
Geographically distributed clusters typically rely on global load balancers, DNS-based routing, or geo-aware proxies to direct traffic efficiently.
Choosing the right topology
There is no one-size-fits-all topology. The best choice depends on organisational size, usage patterns, and operational preferences. One of the strengths of the Stalwart architecture is that topologies are flexible and can be adjusted over time. A simple unified model can be a starting point, with a transition to a more specialised layout as needs evolve.
Approaches can also be mixed and matched, running unified nodes alongside dedicated ones, or shifting services dynamically as demand grows.