Browse Source

new: doc: [synapse] add a ``README.rst`` that was written at the time of the charm

Signed-off-by: Valentin Lab <>
Valentin Lab 2 years ago
  1. 100


@ -0,0 +1,100 @@
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).
As it was difficult to gather information from synapse, here is a quick
recap of most useful concepts and references::
- Ansible recipe:
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.
To enable federation and having a delegate server (ie:
```` for the server managing ````
ids... for instance to use ```` for user id instead of
```` even if you matrix server is on
````), there are 2 options, and only one is fully
working as expected (spoiler alert, it is the ``.well-known``
The reference spec is there:
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 ````'s IP and
will contact this IP asking ``Host:``).
Which will mess with SSL certificate names of course if you are
actually having 2 separated virtual hosts with separate SSL
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.<> <ttl> IN SRV
> 10 0 <port> <>``. The DNS record should then look
> something like:
> $ dig -t srv
> 3600 IN SRV 10 0 8448
> 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:
.well-known method