Cross-Server Mail

Cross-Server Mail

Mail works across multiple servers. Set up a shared database, add a message bus, and players can send mail to anyone on any server. If the recipient’s online — even on a different server — they get notified instantly.

---

Requirements

You’ll need three things:

1. Shared database — MongoDB or MariaDB. All servers must point to the same instance. SQLite won’t work here because it’s a local file.
2. Message bus — Redis or NATS. This is how servers tell each other about new mail in real time.
3. Unique serverId — Each server needs a distinct identifier so the message bus routes notifications correctly.

Unique Server IDs Are Critical

If two servers share the same serverId, message routing breaks. Notifications can get lost, duplicated, or delivered to the wrong server. Double-check every server has a unique ID before going live.

All cross-server configuration lives in Ceremony’s config, not Courier’s.

File: config/ceremony/config.conf (on each server)

---

Database Setup

Point all servers at the same database.

MongoDB:

storageType = MONGO_DB
storageUrl = "mongodb://localhost:27017"

MariaDB:

storageType = MARIA_DB
storageUrl = "jdbc:mariadb://localhost:3306/courier"

---

Message Bus Setup

Redis

messageBus {
  type = REDIS
  serverId = "lobby-1"
  redisAddress = "redis://your-redis-host:6379"
  redisPassword = ""
}

NATS

messageBus {
  type = NATS
  serverId = "survival-1"
  natsAddress = "nats://your-nats-host:4222"
}

---

How Delivery Works

1. A player sends mail on Server A
2. The mail is stored in the shared database immediately
3. A notification goes out on the message bus
4. If the recipient’s online on Server B, they get notified instantly
5. If they’re offline, they’ll hear about it when they next log in on any server

Mail is written to the database first, so nothing’s lost even if the message bus goes down temporarily. The bus is only for real-time notifications — the mail itself is always safe.

---

Distributed Rate Limiting

Rate limits are shared across servers when you’re using a shared database. If a player sends 5 messages on Server A, that counts toward their limit on Server B too. No bypassing limits by server-hopping.

---

Single-Server Setup

Running one server? You don’t need any of this. The defaults work out of the box:

messageBus {
  type = NONE
}

SQLite Is Fine for Single Servers

The default SQLite storage works perfectly on a single server. Only switch to MongoDB or MariaDB when you need shared storage across multiple servers.

---

Troubleshooting

Problem	What to Check
Mail not appearing on other servers	Verify all servers point to the same database URL and credentials
No real-time notifications across servers	Check that the message bus type, address, and credentials match on all servers
Duplicate or missing notifications	Confirm every server has a unique serverId
Connection refused errors	Make sure your database and message bus hosts are reachable from all server machines
Rate limits not shared	You’re probably still on SQLite — switch to MongoDB or MariaDB

---

Next Steps

• Notifications — configure how players hear about new mail
• Moderation & Safety — rate limiting and abuse prevention across servers
• Installation Guide — initial server setup and dependencies