Add selfhostedsynapse.adoc

asciidoc/selfhostedsynapse.adoc

@@ -0,0 +1,100 @@
+# Self-hosting a Matrix server
+Lukáš Kucharczyk
+:toc: left
+:doctype: book
+:source-highlighter: highlightjs
+
+== Assumptions
+This article will be using:
+
+- Docker containers to host the below software
+- the https://matrix.org/docs/projects/server/synapse[Synapse] Matrix server
+- PostgreSQL database for the Synapse server
+- NGINX as the reverse proxy
+
+You will also need:
+
+- a domain name and SSL certificate for it
+
+== Create PostgreSQL user and database
+Reference: https://matrix-org.github.io/synapse/latest/postgres.html#set-up-database
+
+Log into the container:
+```bash
+docker exec -it postgres bash
+```
+Create the user `synapse_user` and use $ADMIN to connect:
+```bash
+createuser --pwprompt -U $ADMIN synapse_user
+```
+Create the database `synapse` and set `synapse_user` as the owner:
+```bash
+createdb --encoding=UTF8 --locale=C --template=template0 --owner=synapse_user -U lukas synapse
+```
+== Synapse
+=== Generate a config file
+Reference: https://github.com/matrix-org/synapse/blob/develop/docker/README.md#generating-a-configuration-file
+
+=== Register a user
+Reference: https://matrix-org.github.io/synapse/latest/setup/installation.html#registering-a-user
+
+Log into the container and create the new user:
+```bash
+register_new_matrix_user -c /data/homeserver.yaml http://localhost:8008
+```
+You will be asked for the `localpart` (as in `localpart@yourserver.tld`), password, and whether to make the user an admin.
+
+=== Delegation
+Reference: https://matrix-org.github.io/synapse/latest/delegate.html
+
+You need to use delegation if the API of your server is not accessible using the default port of 8448 and the provided `server_name`footnote:[https://matrix-org.github.io/synapse/latest/delegate.html#when-do-i-need-delegation].
+
+Not using the default `server_name` is particularly useful for cleaner usernames: instead of `user.subdomain.domain.tld`, you can use `user.domain.tld`.
+
+Delegation is done by providing JSON files at two locations on your serverfootnote:[https://matrix-org.github.io/synapse/latest/setup/installation.html#client-well-known-uri]:
+
+1. https://domain.tld/.well-known/matrix/server
+2. https://domain.tld/.well-known/matrix/client
+
+The `server` part should return this JSON:
+```json
+{
+    "m.server": "subdomain.domain.tld:443"
+}
+```
+The `client` part should return this JSON:
+```json
+{
+    "m.homeserver": {
+        "base_url": "https://subdomain.tld"
+    }
+}
+```
+A simple way to provide these two JSON files using NGINX is to directly return them as a JSON upon request instead of making them actual files on disk:
+
+```nginx
+location /.well-known/matrix/server {
+  add_header Access-Control-Allow-Origin *;
+  default_type application/json;
+  return 200 '{"m.server":"subdomain.domain.tld:443"}';
+}
+location /.well-known/matrix/client {
+  add_header Access-Control-Allow-Origin *;
+  default_type application/json;
+  return 200 '{"m.homeserver":{"base_url":"https://subdomain.tld"}}';
+}
+```
+
+=== Federation
+Reference: https://matrix-org.github.io/synapse/latest/federate.html
+
+To make sure federation is working, you need to redirect certain URL patterns to be handled by the Synapse server, and you also need to use <<Delegation>> in case the Synapse server does not match your base URL.
+
+To redirect the URL patterns to your Synapse server using NGINX, add this configurationfootnote:[https://github.com/matrix-org/synapse/blob/develop/docs/reverse_proxy.md#nginx]:
+```nginx
+location ~* ^(\/_matrix|\/_synapse\/client) {
+  proxy_pass http://$host:$port;
+  proxy_set_header X-Forwarded-For $remote_addr;
+  proxy_set_header X-Forwarded-Proto $scheme;
+  proxy_set_header Host $host;
+```