Opiniated choice of this charm ============================== - As API is REST and compatible to be on same port, ``synapse`` server and client will be served on the same port 8008. This will allow one-port communication that can be reverse-proxified easily and is usually open even in tight controlled network environment. - for simplicity sake, one-responsibility and consistency, SSL support is delegated to ``web_proxy``. So any ACME support on synapse side is disabled. - Departing from standard ``8448`` port for federation support requires some delegation support to be implemented, either with DNS ``SRV`` method, or with ``.well-known`` method. The second is chosen as the first was declared as temporary, and is flawed (see section talking of that). A third reason is that ``DNS`` charm is still not written so that is something we don't have control on yet easily whereas ``.well-known`` host might be easier to implement in existing ``web-proxy`` charms (even if not trivial). Information =========== As it was difficult to gather information from synapse, here is a quick recap of most useful concepts and references:: - Ansible recipe: https://github.com/spantaleev/matrix-docker-ansible-deploy Which is very complete on a fully featured deployment. With real code that is readable. This was a keypoint for a working example providing a ``.well-known`` delegation that actually works. But it also sports LDAP auth, mxid, or whatsapp and telegram bridges config that might become handy soon. Delegation ========== To enable federation and having a delegate server (ie: ``matrix.domain.com`` for the server managing ``domain.com`` ids... for instance to use ``@user:domain.com`` for user id instead of ``@user:matrix.domain.com`` even if you matrix server is on ``matrix.domain.com``), there are 2 options, and only one is fully working as expected (spoiler alert, it is the ``.well-known`` solution). The reference spec is there: https://matrix.org/docs/spec/server_server/r0.1.1.html#resolving-server-names DNS SRV method -------------- This method uses the ``SRV`` DNS record. It is flawed in the way that if we provide the delegated hostname, the actual delegated hostname itself won't be used directly, it will be used only to resolv an IP, and then the HTTPS will set ``Host:`` header to the former hostname, not the delegate, (in our example, it'll contact ``matrix.domain.org``'s IP and will contact this IP asking ``Host: domain.org``). Which will mess with SSL certificate names of course if you are actually having 2 separated virtual hosts with separate SSL certificates. This is how to set up the DNS record according to synapse docs:: > To use a SRV record, first create your SRV record and publish it in DNS. > This should have the format ``_matrix._tcp. IN SRV > 10 0 ``. The DNS record should then look > something like: > > $ dig -t srv _matrix._tcp.example.com > _matrix._tcp.example.com. 3600 IN SRV 10 0 8448 synapse.example.com. > > Note that the server hostname cannot be an alias (CNAME record): it has > to point directly to the server hosting the synapse instance. Note: DNS ``SRV`` method is said to be temporary. The rationale behind this "flaw" is laid down here: https://github.com/matrix-org/matrix-doc/blob/master/proposals/1711-x509-for-federation.md#interaction-with-srv-records .well-known method ------------------ https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/matrix-base/templates/static-files/well-known/matrix-server.j2 Troubleshooting =============== https://matrix.org/federationtester https://matrix.org/federationtester/api/report?server_name=DOMAIN