📄️ Overview
Configuring Stalwart to run in a clustered environment is designed to be straightforward and flexible. The system was built from the ground up to support distributed deployments, allowing administrators to scale horizontally and build highly available infrastructures with minimal overhead.
📄️ Node ID
Each Stalwart instance in a cluster must be assigned a unique identifier to distinguish it from other nodes. This identifier is configured using the cluster.node-id setting and must be a positive integer. It plays a critical role in coordination, logging, and internal message routing, allowing each node to be uniquely addressed within the cluster.
📄️ Coordination Mechanism
Stalwart requires a coordination mechanism to enable communication between nodes in a cluster. Coordination allows nodes to exchange internal updates, detect failures, and remain synchronized during operation. For a full overview of how coordination works and the available options (such as peer-to-peer, Kafka, NATS, and Redis), refer to the Coordination section of this documentation.
📄️ Load Balancing
By default, Stalwart automatically assigns the server hostname based on the underlying system's hostname during installation. This hostname is used in protocol responses, logging, and internal identification. However, when Stalwart is deployed behind a load balancer, it's important that all backend nodes use a consistent hostname that matches the public-facing identity of the service. This ensures uniformity in client communications and protocol-level interactions, particularly for protocols like SMTP, which expose the server’s hostname during the handshake.
📄️ Roles
In a clustered deployment, certain background and maintenance tasks must be performed regularly to keep the system healthy, efficient, and secure. To distribute this operational workload across the cluster, Stalwart allows administrators to assign roles to specific nodes using the cluster.roles settings.