From 56c3fc13b438cd09d4645cf6420dc562ec022250 Mon Sep 17 00:00:00 2001 From: Hans van Zijst Date: Tue, 7 Jan 2025 11:34:27 +0100 Subject: [PATCH] Added checklist to guide the installation process. --- matrix/README.md | 41 +++++++++++++++++++------ matrix/checklist.md | 75 +++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 107 insertions(+), 9 deletions(-) create mode 100644 matrix/checklist.md diff --git a/matrix/README.md b/matrix/README.md index 1424c83..a47e8e6 100644 --- a/matrix/README.md +++ b/matrix/README.md @@ -5,10 +5,13 @@ include_toc: true # A complete Matrix installation -This is going to be a Matrix installation with all bells and whistles. Not -just the server, but every other bit that you need or want. +This documentation describes how to build a complete Matrix environment with +all bells and whistles. Not just the Synapse server, but (almost) every bit +you want. + +The main focus will be on the server itself, Synapse, but there's a lot more +than just that. -We're building it with workers, so it will scale. ## Overview @@ -24,8 +27,8 @@ conferencing * [Consent tracking](https://element-hq.github.io/synapse/latest/consent_tracking.html) * Authentication via -[OpenID](https://element-hq.github.io/synapse/latest/openid.html) -* Several [bridges](https://matrix.org/ecosystem/bridges/) +[OpenID](https://element-hq.github.io/synapse/latest/openid.html) (later) +* Several [bridges](https://matrix.org/ecosystem/bridges/) (later) # Overview @@ -35,15 +38,30 @@ platform, with all bells and whistles. Several components are involved and finishing the installation of one can be necessary for the installation of the next. -These are the components we're going to use +Before you start, make sure you take a look at the [checklist](checklist.md). + +These are the components we're going to use: + ## Synapse -This is the core component: the Matrix server itself. +This is the core component: the Matrix server itself, you should probably +install this first. -Installation and configuration is documented under [synapse](synapse). +Because not every usecase is the same, we'll describe two different +architectures: -You should probably install this first. +** [Monolithic](synapse) + +This is the default way of installing Synapse, this is suitable for scenarios +with not too many users, and, importantly, users do not join many very crowded +rooms. + +** [Worker-based](synapse/workers) + +For servers that get a bigger load, for example those that host users that use +many big rooms, we'll describe how to process that higher load by distributing +it over workers. ## PostgreSQL @@ -52,6 +70,10 @@ This is the database Synapse uses. This should be the first thing you install after Synapse, and once you're done, reconfigure the default Synapse install to use PostgreSQL. +If you have already added stuff to the SQLite database that Synapse installs +by default that you don't want to lose: [here's how to migrate from SQLite to +PostgreSQL](https://element-hq.github.io/synapse/latest/postgres.html#porting-from-sqlite). + ## nginx @@ -94,3 +116,4 @@ yet. With Draupnir you can do moderation. It requires a few changes to both Synapse and nginx, here's how to [install and configure Draupnir](draupnir). + diff --git a/matrix/checklist.md b/matrix/checklist.md new file mode 100644 index 0000000..456bef1 --- /dev/null +++ b/matrix/checklist.md @@ -0,0 +1,75 @@ +# Checklist + +Before you dive in and start installing, you should do a little planning +ahead. Ask yourself what you expect from your server. + +Is it a small server, just for yourself and some friends and family, or for +your hundreds of colleagues at work? Is it for private use, or do you need +decent moderation tools? Do you need audio and videoconferencing or not? + + +# Requirements + +It's difficult to specify hardware requirements upfront, because they don't +really depend on the number of users you have, but on their behaviour. A +server with users who don't engage in busy rooms like +[#matrix:matrix.org](https://matrix.to/#/#matrix:matrix.org) doesn't need more +than 2 CPU cores, 8GB of RAM and 50GB of diskspace. + +A server with users who do join very busy rooms, can easily eat 4 cores and +16GB of RAM. Or more. Or even much more. + +During its life, the server may need more resources, if users change +their behaviour. Or less. There's no one-size-fits-all approach. + +If you have no idea, you should probably start with 2 cores, 8GB RAM and some +50GB diskspace, and follow the [monolithic setup](synapse). + +If you expect a higher load (you might get there sooner than you think), you +should probably follow the [worker-based setup](synapse/workers), because +changing the architecture from monolithic to worker-based once the server is +already in use, is a tricky task. + + +# DNS and certificates + +You'll need to configure several things in DNS, and you're going to need a +couple of TLS-certificates. Best to configure those DNS entries first, so that +you can quickly generate the certificates once you're there. + +It's usually a good idea to keep the TTL of all these records very low while +installing and configuring, so that you can quickly change records without +having to wait for the TTL to expire. Setting a TTL of 300 (5 minutes) should +be fine. Once everything is in place and working, you should probably increase +it to a more production ready value, like 3600 (1 hour) or more. + +What do you need? Well, first of all you need a domain. In this documentation +we'll use `example.com`, you'll need to substitute that with your own domain. + +Under the top of that domain, you'll need to host 2 files under +`/.well-known`, so you'll need a webserver there, using a valid +TLS-certificate. This doesn't have to be the same machine as the one you're +installing Synapse on. In fact, it usually isn't. + +Assuming you're hosting Matrix on the machine `matrix.example.com`, you need +at least an `A` record in DNS, and -if you have IPv6 support, which you +should- an `AAAA` record too. **YOU CAN NOT USE A CNAME FOR THIS RECORD!** +You'll need a valid TLS-certificate for `matrix.example.com` too. + +You'll probably want the webclient too, so that users aren't forced to use an +app on their phone or install the desktop client on their PC. You should never +run the web client on the same name as the server, that opens you up for all +kinds of Cross-Site-Scripting attack. We'll assume you use +`element.example.com` for the web client. You need a DNS entry for that. This +can be a CNAME, but make sure you have a TLS-certificate with the correct name +on it. + +If you install a [TURN-server](coturn), either for legacy calls or for [Element +Call](element-call) (or both), you need a DNS entry for that too, and -again- a +TLS-certificate. We'll use `turn.example.com` for this. + +If you install Element Call (and why shouldn't you?), you need a DNS entry plus +certificate for that, let's assume you use `call.example.com` for that. This +can be a CNAME again. Element Call uses [LiveKit](element-call#livekit) for the +actual processing of audio and video, and that needs its own DNS entry and certificate +too. We'll use `livekit.example.com`.