Skip to content

Synapse App


Matrix is an open network for secure, decentralized communication.

Post installation

Step 1: Select Matrix IDs

Just like email, users on matrix has a unique universal id. These ids are of the form

To give users a "memorable id", this app (also known as home server) is pre-setup to use the second level domain for the domain part of the id (also known as the server_name). For example, if you installed the app at, this app package will set the server_name to This will generate user ids of the form

If you require a different server name, use a File Manager to edit /app/data/configs/homeserver.yaml and restart the app.

Step 2: Delegation

Matrix clients and other matrix servers discover the Matrix server for an ID using Well-Known URIs. The Well-Known URI is a document that is served up from the server_name domain (i.e that delegates the handling to another server (i.e

Step 2.1: Setup

If server_name is hosted on Cloudron, all you have to do is to SSH into Cloudron and create the following file:

mkdir -p /home/yellowtent/boxdata/well-known/
echo '{ "m.server": "" }' > /home/yellowtent/boxdata/well-known/

Be sure to replace with your server_name and with the location of this app.

Step 2.2: Re-configure

Go to the Location page of and click Save. This essentialy re-generates the nginx config. The new nginx config serves up .well-known docs from the above server location

Step 2.3 Verify setup

To verify that the above changes worked, try this command from your laptop/PC:

$ curl
{ "m.server": "" }

If server_name is not hosted on Cloudron, you have to arrange for the above file to be served based on your setup.

.well-known setup is required

The .well-known setup is required for matrix clients to connect. This is the case even when server_name matches the home server location. This is because this app sets up federation on port 443 but the default is port 8448.

Step 3. Federation

Federation setup is automatic. Use the Federation Tester to verify that everything is setup properly. Note you must enter the server_name (like in the form field in the website and NOT the location of your home server (despite what the form says).


To make an existing user an admin, open a Web terminal and run the following command:



Synapse offers a variety of customizations. To make changes, use a File Manager to edit /app/data/configs/homeserver.yaml and restart the app.

Home page

The index.html can be customized by editing /app/data/index.html. Note that any assets have to be embedded inline.