Room federation is the ability of matrix.org to synchronize a global account directory, typically ran by matrix.org, with a (federated) home server ran privately. The matrix.org technology permits full federation without having to use matrix.org at all, yet matrix.org works for any entry-level user that wants to connect to some room without running their own private homeserver. If federation does not work, then typically users should not be able to log-in from matrix.org and see updated message from the home server or users on the home server do not see messages posted by users on matrix.org.

Here are the possible causes for room federation not working for matrix.org:

• matrix.org delegation not working properly on the home server

Apache2 can be placed in front of matrix-synapse in order to reverse proxy requests and serve the matrix.org server assets. If your infrastructure is built with Apache2 as a web-server then the advantage is that everything can be contained within the same application. The official reverse proxy instructions work great but they are incomplete when it comes to configuring delegation for matrix.org.

The following is a full reverse-proxy configuration:

<VirtualHost *:80>
    ServerAdmin office@server.tld
    ServerName matrix.server.tld
 
    Protocols h2 h2c http/1.1
 
    DocumentRoot /var/www/matrix.server.tld
 
    RequestHeader set "X-Forwarded-Proto" expr=%{REQUEST_SCHEME}
    AllowEncodedSlashes NoDecode
    ProxyPreserveHost on
    ProxyPass /_matrix http://127.0.0.1:8008/_matrix nocanon
    ProxyPassReverse /_matrix http://127.0.0.1:8008/_matrix
    ProxyPass /_synapse/client http://127.0.0.1:8008/_synapse/client nocanon
    ProxyPassReverse /_synapse/client http://127.0.0.1:8008/_synapse/client
 
    Alias /.well-known/matrix/client /var/www/matrix.server.tld/client.json
    <Location "/.well-known/matrix/client">
        ForceType application/json
        Header set Access-Control-Allow-Origin *
    </Location>
 
    Alias /.well-known/matrix/server /var/www/matrix.server.tld/server.json
    <Location "/.well-known/matrix/server">
        ForceType application/json
        Header set Access-Control-Allow-Origin *
    </Location>
 
    ErrorLog "/var/log/apache2/matrix.server.tld-error.log"
    CustomLog "/var/log/apache2/matrix.server.tld-access.log" common
</VirtualHost>

under the following assumptions:

• server.tld, is a placeholder for a hostname and TLD,
• matrix.server.tld is a placeholder for a FQDN (subdomain, hostname and TLD),
• /var/www/matrix.server.tld is a directory accessible to Apache that contains two files:
  • /var/www/matrix.server.tld/client.json with the following contents {"m.homeserver":{"base_url":"https://matrix.server.tld"},"m.identity_server":{"base_url":"https://matrix.server.tld"}}
  • /var/www/matrix.server.tld/server.json with the following contents {"m.server": "matrix.server.tld:443"}