Server Name Is Permanent#

The most important decision you make is server_name in the Synapse config. This is the domain that appears in every user ID. If you set it to matrix.example.com, your users will be @name:matrix.example.com. If you set it to example.com, they will be @name:example.com.

You want the bare domain. Shorter IDs look better and are easier to share. But here is the catch: once you set the server name and create the first user, you cannot change it. Ever. The signing keys, room IDs, and event hashes are all tied to that name. Changing it means starting over.

I went with the bare domain and use well-known delegation to tell other servers that the actual homeserver lives at a subdomain.

Well-Known Delegation#

When another Matrix server wants to talk to yours, it looks up your server name. If your server name is example.com but Synapse runs on matrix.example.com, the remote server needs a way to discover that.

You serve two JSON endpoints on the bare domain:

The server endpoint returns which host and port handles federation. The client endpoint returns where the client API lives. Both are tiny JSON responses that Caddy can serve inline with the respond directive. No files, no separate service.

The important detail that the docs barely mention: the client well-known response needs a CORS header. Specifically Access-Control-Allow-Origin: *. Without it, Element Web running in a browser cannot discover the homeserver. You will stare at a login screen that says it cannot reach the server and wonder what you did wrong.

Cloudflare and Federation#

If your domain is behind Cloudflare, federation works fine as long as you set up the well-known endpoints correctly. Federation traffic goes through port 443, which Cloudflare proxies without issues.

The one thing to watch: Cloudflare has a 100-second timeout on the free plan. For a small personal server this is irrelevant, but if you ever end up in a large federated room, the initial sync could theoretically hit that limit.

I have been in rooms with several hundred members and never hit the timeout. But it is worth knowing about.

Voice and Video Calls#

Element supports one-to-one and group calls, but they need a TURN server to relay media when direct peer-to-peer connections fail. This happens more often than you would think. Corporate firewalls, symmetric NAT, and mobile carriers all block direct WebRTC connections.

I already had a coturn server running for another project. Adding Matrix support was just a matter of generating a shared secret and putting it in the Synapse config. Synapse generates time-limited TURN credentials for each call using HMAC, which is more secure than static credentials.

The config in Synapse points to the TURN server by IP address, not hostname. This avoids DNS resolution issues. You list both UDP and TCP transport options so clients behind restrictive firewalls can fall back to TCP.

Testing calls is annoying because you need two separate accounts on two separate devices. You cannot call yourself. I created a test account, logged in on my phone, and called from my laptop. The first call had one-way audio because the TURN server was binding relay ports on Docker internal IPs instead of the public IP. Adding --relay-ip and --listening-ip flags to coturn fixed it immediately.

Registration and Invites#

I started with invite-only registration using tokens. Synapse has a built-in token system where you generate a token, give it to someone, and they use it during registration. Each token can be limited to a single use.

Then I realized I was the only one creating accounts, so I just opened registration entirely. Synapse will complain about open registration without verification, but you can silence that with a config flag. For a small server with friends, the spam risk is minimal.

If spam does become a problem, switching back to token-based registration is a one-line config change. No need to over-engineer it upfront.

Password Policy#

Synapse has a built-in password strength checker that rejects most passwords. It is aggressive. Passwords that I considered perfectly fine were being rejected. The policy can be disabled in the config, which I did immediately.

Element Web also has its own client-side password strength check that is separate from the server policy. Even after disabling the server policy, Element still complained. That one I could not disable through config. It is more of an annoyance than a blocker since it warns but does not prevent you from proceeding.

Resource Usage#

Synapse is the heaviest thing on my server. At idle with a handful of users, it uses about 300 megabytes. During federation sync or when someone joins a large room, it can spike to a gigabyte.

The PostgreSQL database backing it uses another 70 megabytes. Element Web is negligible since it is just static files served by nginx in a container.

The config has a caches.global_factor setting that controls memory usage. The default is 0.5. Turning it down to 0.3 reduces memory at the cost of more database queries. For a small server the difference is not noticeable.

Was It Worth the Effort#

Absolutely. My friends and I have a chat platform that we fully control. Voice calls work, screen sharing works, file sharing works. The web client means nobody has to install anything. And because it federates, anyone on any Matrix server can reach us if they know our addresses.

The setup took about two hours. Most of that was the TURN server configuration and testing calls. If you skip voice and video, you could have it running in thirty minutes.

It sounds like a mess, but it is actually pretty clean. The trick is structure: one compose file, two networks and some naming discipline.

One Compose File, Two Networks#

Every service lives in a single docker-compose.yml. I tried splitting it into multiple compose files early on and it was a nightmare. Services that need to talk to each other end up on different networks, you forget which file defines what, and debugging becomes archaeology.

One file means one place to look. The trade-off is that the file is about 200 lines long, but that is way better than hunting through five separate files.

The networking is simple: two Docker bridge networks. The first one connects Caddy to the internet. The second one connects Caddy to every backend service. Services that need to be reached by Caddy join the backend network. Services that need direct port access to the internet get explicit port mappings.

The WireGuard container is the exception. It runs with host networking because it needs raw access to the network stack for the VPN tunnel. Everything else uses the bridge networks.

Container Naming#

I name every container explicitly with container_name. Docker Compose generates names like wleeaf-caddy-1 by default, which is ugly in logs and hard to type in commands. Explicit names mean I can do docker logs caddy instead of docker logs wleeaf-caddy-1.

This also matters for DNS resolution inside Docker networks. When you give a container a name, other containers on the same network can reach it by that name. So my Caddy config just says reverse_proxy gitea:3000 and Docker handles the resolution.

Resource Reality#

People overestimate how much RAM you need. Here is what my containers actually use:

The reverse proxy sits at 15 megabytes. The git server uses about 110. The mail server is the hungriest at 160. The Matrix homeserver varies between 100 and 500 depending on federation activity. The database backing it uses 70. Everything else is under 50 each.

Total memory usage hovers around 2.5 gigabytes. That leaves five gigs free for spikes, builds, and the occasional agent session eating a gig for a few minutes.

CPU is basically idle. The load average rarely goes above 0.1 unless someone is building a Docker image or running a CI job. Four cores is overkill for this workload.

Secrets Management#

I keep secrets in a .env file next to the compose file. Docker Compose reads it automatically. Database passwords, API tokens, and hashed passwords all live there. The compose file references them with the dollar-sign-curly-brace syntax.

The .env file is not in any git repo. I back it up manually. Some people use Docker secrets or Vault for this, but for a single-server personal setup, a .env file is fine.

Restart Policies#

Every service has restart: unless-stopped. This means containers come back after a reboot or a crash, but stay down if I explicitly stop them. I used to use always but that fights you when you are debugging, because the container keeps restarting while you are trying to read the logs.

The one exception is the CI runner. It has restart: unless-stopped too, but I sometimes need to stop it to free resources during heavy builds. With unless-stopped, it stays down until I bring it back up.

Volume Strategy#

I mount named directories from the host filesystem, not Docker volumes. Every service gets a directory under the main project folder. Caddy gets ./caddy, Gitea gets ./gitea, the mail server gets ./stalwart, and so on.

This makes backups trivial. I can tar the entire project directory and I have everything: configs, data, and the compose file itself. Docker volumes are fine, but they hide the data in a location you have to look up every time.

The Upgrade Dance#

Upgrading a service usually means changing the image tag and running docker compose up -d. For services using latest, I pull first with docker compose pull and then bring them up.

I do not use Watchtower or any automatic update tool. I want to know exactly when things change. An automatic update at 3 AM that breaks the mail server is not a problem I want to have.

The whole setup has been running for months with essentially zero unplanned downtime. The only time services go down is when I am actively working on them. For a personal infrastructure project, that is more than good enough.

The usual advice goes something like this: spam filters will eat your messages, IP reputation is impossible to build, and you will spend your weekends debugging DKIM signatures instead of doing anything useful. After a couple weeks of running Stalwart on a cheap Hetzner VPS, I can say that some of those warnings are legitimate but most of them are outdated.

The Setup#

I went with Stalwart, which is a relatively new mail server written in Rust. It handles SMTP, IMAP, and JMAP out of the box, and the admin UI is surprisingly decent for a self-hosted project. The whole thing runs in a single Docker container with a RocksDB backend, which means no separate database to manage.

The stack looks like this:

• Stalwart for mail handling on ports 25, 465, 587, and 993
• Caddy as the reverse proxy with a wildcard TLS cert
• SnappyMail for webmail access
• Cloudflare for DNS on the free plan

The VPS itself is nothing special. 4 cores, 8 gigs of RAM, running Ubuntu 24.04. Stalwart barely touches the resources and sits at around 150MB of RAM even after a few thousand messages.

DNS Was the Easy Part#

Setting up DNS records is the part that scares most people, but it is genuinely straightforward if you take it step by step. You need an A record for your mail subdomain, an MX record pointing to it, SPF to declare which IPs can send for your domain, DKIM for cryptographic signature verification, and DMARC to set a policy for failed checks.

The Cloudflare API makes all of this scriptable. I wrote a shell script that creates all five records in about 30 seconds. The DKIM key was the only tricky part because Stalwart generates it internally and you have to copy it out of the admin panel and paste it into DNS.

The Reputation Problem#

This is the real challenge. When you spin up a brand new IP and start sending mail, every major provider treats you with suspicion. Gmail sent my first few messages straight to spam even though SPF, DKIM, and DMARC all passed perfectly.

The fix was not technical, it was behavioral. I marked those messages as not spam in my Gmail account, added the addresses to my contacts, and started having normal conversations. Within a few days, Gmail stopped flagging my messages. Google Postmaster Tools confirmed that the domain reputation was climbing.

One thing that helped: my VPS provider has decent IP reputation to begin with. If you are on a provider known for abuse, you will have a much harder time. Also make sure your reverse DNS is set correctly because Gmail checks that the PTR record for your IP matches your mail hostname.

TLS Certificate Sharing#

I did not want to manage separate certificates for the mail server. Caddy already handles TLS for all my subdomains using a wildcard cert from Lets Encrypt via DNS challenge. I just mounted the certificate directory read-only into the Stalwart container.

The only catch is that Caddy stores the cert in a specific directory structure and you need to figure out the exact path. Once you find that, a volume mount in Docker Compose is all you need.

Was It Worth It#

Honestly, yes. The total ongoing cost is zero beyond the VPS I was already paying for. I have full control over my email, the data never touches a third party, and the whole thing took an afternoon to set up.

The one thing I would do differently: I would have registered my domain and set up the mail server on the same day. Domain age matters for reputation, and the sooner you start sending from a domain, the sooner it builds trust with the big providers.

If you are already running a VPS for other things, adding a mail server is a no-brainer. If you are starting from scratch just for email, you might want to think about whether the learning experience is worth the first week of dealing with spam folders.