Choosing the Red Pill

Creating Users

To register new users, go to the command-line interface (CLI) of the host in the running Synapse container and enter:

podman exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml <username>

Specify a password and give the initial user admin rights. In a larger setup, of course, you will not generate all users manually on the CLI. Synapse has several authentication plugins; you can use single sign-on with different ID providers or add the enable_registration = true target in the homeserver.yaml file. Be careful, though, because it allows any user with access to the server to create an account. You will only want to enable this function on the local network as long as the server is not yet accessible over the Internet.

Matrix separates the client from the server. The Synapse server itself does not have a web user interface (UI). Administration is by the CLI, the REST API, or external tools with access to the admin REST API. You can find a number of different clients for using the service. Element is probably the most popular, and you can use it as a web service in your browser by going to https://element.io, or you can download client apps for Windows, Linux, or macOS from the website. Element is also available free of charge for iOS and Android in the Apple and Google app stores.

In the Element client, instead of matrix.org , enter the URL of your Matrix server (in this example, https://matrix.domain.com). After logging in with the initial account and the assigned password, Element prompts you to set up a secure backup and create a secure key for end-to-end encryption. Be sure to store it in a safe place after generating this key. Now you can only connect new clients to your account if you either specify this key or use two-factor authentication on a previously registered client. At this point, it makes sense to link a mobile client on your phone to the account. You can then unlock additional clients by QR code that Element scans and verifies on your phone.

User Interface for Admins

In addition to Element as a messaging client app you can find a few admin UI projects. These work, but with limitations. The reverse proxy configuration provided above only exposes the messaging API (/_matrix and /_synapse/client) to the Internet, but not the admin API (/_synapse/admin), and it is a good idea to keep things that way. However, in this example, you could launch an admin web UI (Figure 1) directly on the hosting server in another container:

Figure 1: Synapse-admin simplifies user management. Bridges that connect to other chat networks automatically generate matching users.

podman run --net virt_net --ip 192.168.122.27 --mac-address 52:54:C0:A8:7A:1b docker.io/awesometechnologies/synapse-admin

Directly on the hosting server, call the URL http:// 192.168.122.27 in the browser. In the connection dialog that follows, enter the admin account and the Matrix URL to match the http://192.168.122.26:8008 example because you are using the internal network connection between the containers and are not routing via the proxy. If your hosting server doesn't have a GUI, you can tunnel the application port of the web UI 192.168.122.27:80 to your client in the usual way over SSH and then use the browser there.

Checking Federation

At this point, your Synapse server is running and the locally created users can communicate through it. Now it is time to test the connection to other matrix domains. First, check whether the federation settings of your server are configured correctly. To do so, simply go to the Matrix Federation Tester [2] and enter your domain name. The federation tester checks both discovery methods over DNS and the well-known REST API. The service also validates the HTTPS certificates. If everything shows up in green, other Matrix users can reach your server, and your users are allowed to communicate with other domains in return.

Matrix manages all chats in rooms. Private chats for Matrix are nothing more than groups with only two members. Communication on the local server and with other Matrix installations is protected by end-to-end encryption. The messages themselves are saved in an encrypted format by the Synapse setup in the specified database.