diff --git a/README.md b/README.md index fe94b6b..a5c97df 100644 --- a/README.md +++ b/README.md @@ -88,6 +88,123 @@ If you are feeling adventurous you can install postgresql using [docker](https:/ Either way, you need to install this on youd DB machine, which should be the one with the least amount of RAM. +## Install Nginx + +You need to install nginx (or apache2, or traefik, whichever you are more comfortable with, but be aware I'll only be able to help with nginx and traefik as I have no idea how apache2 works). Use ansible for this, and install the `nginx-extras` package, because why not. + ## Create a certificate for our deployments +While you are at it you might as well create two DNS `A` fields to point at OpenWRT (which will forward it to nginx). + We need to use a certificate to secure HTTPS communication, both the Mastodon and Matrix protocols require it. This can be done manually for the moment and automated later, as it is not super straightforward. I refer you to the [documentation on certbot + nginx](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-20-04) I would recommend that you create a `mastodon.` and a `matrix.` certificate, then back them up somewhere safe as Letsencrypt has pretty aggressive rate limiting with regard to certificate creations. + +## Let's install Synapse + +Synapse is the messaging app I told you about. + +### Preconfigure synapse + +I would recommend you read quickly through this [synapse install guide](https://hub.docker.com/r/matrixdotorg/synapse/) so you understand what you are doing before touching anyting! + +In essence you need to run the following command in your lab machine: + +``` +$ docker run -it --rm \ + -v $(pwd)/synapse-data:/data \ + -e SYNAPSE_SERVER_NAME=matrix. \ + -e SYNAPSE_REPORT_STATS=no \ + matrixdotorg/synapse:latest generate +``` + +:warning: careful this is not the same command as in the documentation above, this will create the files you need in a `synapse-data` directory in your working directory, which is probably what you want in order to send them to your host via ansible. + +Create a new role and copy over these files to `roles/synapse/files`. + +Next customise the configuration file. If you feel like using postgres (you already set it up so why not, right ?) check the [docs](https://matrix-org.github.io/synapse/latest/usage/configuration/config_documentation.html#database). + +## Create the synapse docker container + +Normally your `synapse` module does not have any tasks yet, so go ahead and create a `roles/synapse/tasks/main.yml` file. You need to use the [`community.docker.docker_container`](https://docs.ansible.com/ansible/latest/collections/community/docker/docker_container_module.html#examples) module for this. In essence you need to make sure of a few things: + +- you want your container to port forward port 8008 in the host + to 8008 in the container either that or you can just use the + `network_mode: host` in the definition +- you want to mount the directory in which you copied the + `homeserver.yaml`, `matrix..log.config` and + `matrix..signing.key` to `/data` in the + container. + +For example, if I wanted to start a `redis` container that forwards 6379 and mounts `/tmp` I would do something like + +```yaml +--- +# This is needed because your host might not have it installed +- name: "Install docker module for python" + pip: + name: docker + executable: pip3 +- name: creates the redis container + community.docker.docker_container: + name: "redis" + image: "{{ redis_image }}:{{ redis_image_tag }}" + state: started + recreate: yes + ports: + - 6379:6379/tcp + volumes: + - /tmp:/tmp + restart_policy: "unless-stopped" +``` + +Note `restart_policy: "unless-stopped"` that ensures that your container is going to: + +- Be started on boot +- Restart in case it crashes + +:information_source: Note that I used `{{ redis_image }}` in the manifest above. These are variables that are available in the same fashion as they are for [templates](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html) which use the [jinja2](https://jinja.palletsprojects.com/en/3.1.x/templates/) markup language. If you want to create a default variable for your module, you can create a `roles//defaults/main.yml` that will contain something like this for example + +```yaml +--- +redis_image: redis +redis_image_tag: latest +``` + +You can override this variable if you want in any of the following: + +- `vars` section of a playbook file +- `host_vars/.yml` file for host specific overrides +- `group_vars/.yml` file for group specific variables + +Now back to synapse, you should have a running container by now, that has a directory mounted with your configuration. Check your container works with the `docker ps` command, you should see something like +``` +root synapse.lil.maurice.fr ~ # docker ps | grep synapse +95aba77cc320 matrixdotorg/synapse:v1.74.0 "/start.py" 2 weeks ago Up 6 days (healthy) 8009/tcp, 0.0.0.0:8008->8008/tcp, 8448/tcp synapse +``` + +### Configure the nginx reverse proxy + +You can see from the configuration that matrix listens on port `8008` for federation and client connexions. + +This means you will need to create one reverse proxy in your Nginx configuration, that will listen on port 443, that will utilise the TLS certificate you have generated earlier, and listens on the servername `matrix.`. To do that, update the configuration of your Nginx role to upload a file to `/etc/nginx/sites-enabled/matrix` looks like something like + +```nginx +server { + listen 443 ssl; + server_name matrix.; + + ssl_protocols TLSv1.2 TLSv1.3; + ssl_ciphers HIGH:!MEDIUM:!LOW:!aNULL:!NULL:!SHA; + ssl_prefer_server_ciphers on; + ssl_session_cache shared:SSL:10m; + ssl_session_tickets off; + + ssl_certificate .crt; + ssl_certificate_key .key; + + location / { + proxy_pass http://127.0.0.1:8008; + } +} +``` + +After a reload of nginx it should work properly.