Added checklist to guide the installation process.

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).
+

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`.