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

Signed-off-by: Valentin Lab <valentin.lab@kalysto.org>

synapse/README.rst

@@ -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).
+
+
+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.<yourdomain.com> <ttl> IN SRV 
+> 10 0 <port> <synapse.server.name>``. 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