#language en

##TAG:TRANSLATION-HEADER-START
~- [[de/FreedomBox/Manual/MatrixSynapse|Deutsch]] - [[FreedomBox/Manual/MatrixSynapse|English]] - [[es/FreedomBox/Manual/MatrixSynapse|Español]] - [[DebianWiki/EditorGuide#translation|(+)]] -~
##TAG:TRANSLATION-HEADER-END

<<TableOfContents()>>

## BEGIN_INCLUDE

== Matrix Synapse (Chat Server) ==
||<tablestyle="float: right;"> {{attachment:Matrix-icon_en_V01.png|Matrix Synapse icon}} ||

'''Available since''': version 0.14.0

=== What is Matrix? ===
[[https://matrix.org/|Matrix]] is an open protocol for interoperable, decentralized, real-time communication over IP. Synapse is the reference implementation of a Matrix server. It can be used to setup instant messaging on !FreedomBox to host chat rooms with end-to-end encrypted communication and audio/video calls.  
Matrix Synapse is a federated application where chat rooms can exist on any server and users from any server in the federated network can join them. [[https://matrix.org/docs/guides/faq.html|Learn more]] about Matrix.

=== How to access your Matrix Synapse server? ===

We recommend the [[https://element.io/|Element]] client to access the Matrix Synapse server. You can [[https://element.io/get-started|download]] Element for desktops.  Mobile applications for Android and iOS are available from their respective app stores.

=== Port Forwarding ===

If your !FreedomBox is behind a router, you will need to set up port forwarding on your router. You should forward the following ports for Matrix:
 * TCP 8448

=== Setting up Matrix Synapse on your FreedomBox ===

To enable Matrix Synapse, first navigate to the Chat Server (Matrix Synapse) page and install it. Matrix needs a valid domain name to be configured. After installation, you will be asked to configure it.  You will be able to select a domain from a drop down menu of available domains.  Domains are configured using [[FreedomBox/Manual/Configure|System -> Configure]] page. After configuring a domain, you will see that the service is running. The service will be accessible on the configured !FreedomBox domain. Currently, you will not be able to change the domain once is it configured.

Your router has to be configured to forward port 8448.

All the registered users of your !FreedomBox will have their Matrix IDs as `@username:domain`. If public registration is enabled, also your chosen client can be used to register a user account.

=== Setting up Audio/Video calls ===

The Matrix Synapse server is only responsible for establishing calls between participants in rooms. Matrix clients such as Element are actually responsible for the transfer of the audio/video traffic. Element supports calling in both one-to-one conversations and in groups.

For one-to-one conversations, Element tries to make a peer-to-peer connection between the two participants. This works when both the participants are using Element on computers with a public IP address or if they're on the same network. If both the participants are behind different NAT devices, establishing a direct peer-to-peer connection between them will not be possible. This problem can be solved by configuring Matrix Synapse with a STUN/TURN server. !FreedomBox provides an app called [[FreedomBox/Manual/Coturn|Coturn]] for this purpose. !FreedomBox doesn't automatically install Coturn on installing Matrix Synapse. However, as soon as Coturn app is installed, !FreedomBox automatically configures Matrix Synapse to use it for audio/video calls. It is possible to override this configuration with a different STUN/TURN server in the web interface.

For calling groups with more than two participants (i.e. not one-on-one conversations), Element uses an external Jitsi Meet instance. Element uses jitsi.riot.im as its default Jitsi Meet instance. If the Matrix Synapse server is configured to use a different Jitsi Meet instance as the default, Element will use it instead for all users on that server. 

=== Federating with other Matrix instances ===

You will be able to interact with any other person running another Matrix instance.  This is done by simply starting a conversation with them using their matrix ID which is of the format `@their-username:their-domain`.  You can also join rooms which are in another server and have audio/video calls with contacts on other server.

=== Memory usage ===
The Synapse reference server implemented in Python is known to be quite RAM hungry, especially when loading large rooms with thousands of members like #matrix:matrix.org. It is recommended to avoid joining such rooms if your !FreedomBox device only has 1 GiB RAM or less. Rooms with up to a hundred members should be safe to join. The Matrix team is working on a new implementation of the Matrix server written in Go called Dendrite which might perform better in low-memory environments.

Some large public rooms in the Matrix network are also available as IRC channels (e.g. #freedombox:matrix.org is also available as #freedombox on irc.debian.org). It is better to use IRC instead of Matrix for such large rooms. You can join the IRC channels using [[FreedomBox/Manual/Quassel|Quassel]].

=== Advanced usage ===

 1. If you wish to create a large number of users on your Matrix Synapse server, use the following commands on a remote shell as root user:
  {{{
cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1 | sed "s+^+registration_shared_secret: +" > /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
chmod 600 /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
chown matrix-synapse:nogroup /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
systemctl restart matrix-synapse
register_new_matrix_user -c /etc/matrix-synapse/conf.d/registration_shared_secret.yaml
}}}
 1. If you wish to see the list of users registered in Matrix Synapse, the following as root user:
  {{{
apt install sqlite3
echo 'select name from users' | sqlite3 /var/lib/matrix-synapse/homeserver.db  
}}}
 1. If you wish to create a community in Matrix Synapse, a Matrix user with server admin privileges is needed. In order to grant such privileges to `username` run the following commands as root user: 
   {{{
sudo apt install sqlite3
echo "UPDATE users SET admin=1 WHERE name='@username:domainname'" | sudo sqlite3 /var/lib/matrix-synapse/homeserver.db  
   }}}  


=== External links ===

 * Upstream project: https://matrix.org
 * Upstream Synapse matrix server project: https://github.com/element-hq/synapse
 * Upstream user documentation: https://matrix.org/docs/chat_basics/matrix-for-im/
 * Debian community wiki: https://wiki.debian.org/Matrix
 * Video tutorial for setting up Matrix Synapse on a Cloud instance: https://youtu.be/8snpMHHbymI

==== Client apps ====
Links to recommended client apps, where applicable, can be found in FreedomBox by select the Apps page, selecting the application tile, and clicking the > Client Apps button. 
 * [[https://wiki.debian.org/Matrix#Clients|Clients in Debian community wiki]]
## END_INCLUDE

Back to [[FreedomBox/Features|Features introduction]] or [[FreedomBox/Manual|manual]] pages.

<<Include(FreedomBox/Portal)>>

----
CategoryFreedomBox
