Prerequisites¶
In order to set up a Continuwuity server, you will need the following:
- A server running Linux (BSD is also supported, but takes a bit more work to set up, and is not covered in this guide).
- A domain name that you own, and can point to your server.
- An internet connection of at least 1Mbps (far more is recommended) that is not behind NAT (see the "getting around NAT" page for more advice if you're on a NAT-ridden connection).
- A basic understanding of how to use the command line, edit files, and use SSH.
- Around half an hour to set it up.
- An IPv4 address (IPv6 only is possible, but most of the federation still doesnt support it, so you will be unable to communicate with most other servers).
Getting a domain name¶
In order to participate in the Matrix network, you will need a domain name. While it is not technically required (you can just use an IP address), you will not be able to join a very large portion of Matrix rooms without a domain name attached to your server.
Getting a domain is actually very cheap - if you aim to use top-level domain names (TLDs) like .com, .net, .org, etc, or country-code TLDs (ccTLDs) like .uk, .de, etc, you can expect to pay around £5-£10 per year for a domain name. It will literally cost you less than a Tesco meal deal.
I personally use Porkbun, which is usually quite cheap. There are other options, such as Namecheap, CloudFlare, Hetzner, and OVH. Starship is also worth a mention.
Do not use "free" domains/providers
They are usually frequently used for abuse, and are commonly blocked from Matrix rooms. Also - if the domain you use expires, you won't be able to continue to use your server, unless you re-register it. This is because your user ID (identity) is tied to your domain name, much like email addresses.
In this example, I'm going to be using Porkbun, because that's where I have all of my domains, and I'm not buying one for the sake of showing you how to do it and set up the server, I'll be re-using one I already have.
Go ahead and pick the domain you want to use, register it, and then come back to this guide, because the next step is:
Planning your DNS records¶
For Matrix, you only actually need one DNS record - the A/AAAA record for your apex (root) domain. Some advanced/complex cases may want to use a subdomain for routing (which is lightly covered below), but for most people, you will only need the apex domain.
Your server name is PERMANENT!
Your server name cannot change after you set it up, so if you want the example.com server name, make sure that you set that. It doesn't matter if you then run matrix on matrix.example.com, but you will need to set the server name to example.com in the config file. More on that later, just keep this in mind.
Furthermore, you must always have control over your server name's domain - it is where other servers will ask where to send further requests. If someone else gains control over the domain associated with your server name, they can impersonate your server.
Here's how I have my records set up for timedout.uk:
| Type | Name | Value | Note |
|---|---|---|---|
| A | timedout.uk | 128.140.107.126 | The IPv4 address of my VPS |
| AAAA | timedout.uk | 2a01:4f8:1c1e:a4f6::1 | The IPv6 address of my VPS |
That's it!
You should point the IP addresses at the server where the below Caddy reverse proxy is running. If you bought a VPS to circumvent NAT/firewall issues, you would point the IP addresses at that server. See below for an example of splitting traffic between the origin and the reverse proxy, if that's something you can and want to do.
Using additional subdomains for split routing
If you want to use a subdomain, you will need additional records. I only recommend this if you want to serve matrix from a different server and don't want to route the traffic through your reverse proxy.
For one of my servers, transgender.ing, I serve client-to-server traffic (things like login, sending messages, downloading images, etc) through my VPS, which applies some caching, but also allows me to absorb a DDOS attack if that happens. However, to reduce federation latency, I serve server-to-server traffic (federation) directly from my home server.
This means I have the following records:
| Type | Name | Value | Note |
|---|---|---|---|
| A | transgender.ing | 128.140.107.126 | The IPv4 address of my VPS. /.well-known/matrix/{client,server,support} is served here |
| AAAA | transgender.ing | 2a01:4f8:1c1e:a4f6::1 | The IPv6 address of my VPS. Same as above. |
| A | matrix.transgender.ing | 128.140.107.126 | Same as the first record, but exclusively serves Matrix client-to-server requests. |
| AAAA | matrix.transgender.ing | 2a01:4f8:1c1e:a4f6::1 | Same as the previous record, but for IPv6. |
| A | matrix-fed.transgender.ing | 88.54.104.52 | The IPv4 address of my home server. Matrix federation (server-to-server) traffic runs over this connection. |
In this case, users with an account on transgender.ing would open their client of choice, put in their user ID, and their client would send a request to https://transgender.ing/.well-known/matrix/client to discover the server. Then, the client will send subsequent requests to https://matrix.transgender.ing/_matrix/client/....
Other servers in the federation will follow a similar flow. They'll see the server name transgender.ing, send a request to https://transgender.ing/.well-known/matrix/server, be told to send traffic to https://matrix-fed.transgender.ing/_matrix/..., and will communicate directly with my home server.
Of course, this is a very complicated example. It could be optimised by not using the matrix subdomain for client-to-server traffic and instead only serving it on the apex domain, but I created that subdomain ages ago and never bothered changing it. The matrix-fed subdomain was set up so that Matrix federation traffic could bypass the reverse proxy on my VPS, instead serving straight from the origin. I did this because I got hit with a DDoS attack that overloaded the link between my VPS and my home server, but my home server was still capable of serving federation traffic, so it allowed me to remain reachable with other servers despite clients and users being unable to actually use the server.
I don't recommend this unless you know what you're doing, and you have a good reason to do it. Even though this is typically how other implementations and guides tell you how to do it, it's generally unnecessary and technically (raw numbers) worse for performance, for most people.
Now that you've got the prerequisites out of the way, you can move on to setting up Caddy.