Adding new ACME-renewable certificate

Questions
1

Your question

Hi,

I run Stalwart as a cluster but in two different locations.
My idea is to use mail2.mydomain for one node and mail3.mydomain for the other.

When configuring the first node, we choose the default hostname. Then ACME is configured and things work from there.

But is it possible to:

  • add a new hostname so that certificates for it are fetched, and
  • assign that hostname to a specific node in the cluster?

I might be getting this all wrong, but what I’m trying to create here is a geographic redundant Stalwart so that when an MX is down, the other node will take over.

2

Here is a clear breakdown of what the docs say for your scenario:

ACME certificates: yes, adding more hostnames is straightforward. Each hostname you want covered gets its own Domain record with certificateManagement set to the Automatic variant, pointing to your existing AcmeProvider. You can add mail2.yourdomain and mail3.yourdomain as separate Domain objects in the WebUI (Settings › TLS › ACME Providers / Domain settings) and each will get its own certificate issued and renewed automatically. A single AcmeProvider can back any number of Domain records.

Per-node hostname assignment: this is where the architecture differs from what you may expect. The docs are explicit that defaultHostname is a cluster-wide singleton – there is no per-node hostname override. Setting it once applies across all nodes. The recommended pattern for a load-balanced/failover cluster is that all nodes share the same public hostname (e.g. mail.mydomain) rather than exposing individual node hostnames (mail2, mail3) to clients.

For geographic redundancy via DNS MX failover, the standard approach is:

  • Publish two MX records for your domain with different priorities, both pointing to the same public name (or two different public names if you want them separate).
  • Each Stalwart node handles inbound mail independently; DNS TTL and MX priority handle failover at the DNS level.
  • Each node would need its own ACME-issued certificate for whatever hostname it advertises – which you can set up as separate Domain records.

The key limitation to be aware of: if your two nodes are in the same Stalwart cluster (sharing a coordinator/data store), the defaultHostname singleton is shared. If they are independent Stalwart installations (not clustered, just with shared DNS MX records for redundancy), each has its own configuration and you can set different hostnames freely.

Relevant docs:

This is an automated reply from the Stalwart Help Bot. Other community members may follow up if this answer is incomplete or wrong.

3

Adding the new ACME-issued hostname is just adding it to a Domain
record (or subjectAlternativeNames of an existing one) with
certificateManagement.Automatic pointing at your existing AcmeProvider:
docs at Configuration | Stalwart.

There’s no per-node certificate binding in Stalwart. In a cluster
every node shares the data store, including ACME state and issued
certificates; any node can serve any hostname. The question of
“which node responds for mail2 vs mail3” is solved at DNS (each
hostname’s A/AAAA record points at the IP of one node), not in
Stalwart config.

4

Thanks @stalwart . I found it under domains. That’s great!
How can I trigger a certificate renewal then? Even after adding the subject alternative name, I guess I need to trigger the acme to request new ones, no?