This repository contains files to "quickly" setup a Matrix Synapse server.
Note that more complex setups can be done using Ansible
- Prepare two domain names for your Matrix (Synapse) server and TURN (CoTURN) server.
Your matrix server will offer Chat services, and the TURN server will allow you to use Webconferences through your Chat with ease.
_matrix._tcp IN SRV 10 5 8448 matrix.example.com
_turn._udp IN SRV 0 0 3478 turn.example.com.
_turn._tcp IN SRV 0 0 3478 turn.example.com.
_turns._tcp IN SRV 0 0 5349 turn.example.com.
_turn._udp IN SRV 0 0 3478 turn.example.com.
_turn._tcp IN SRV 0 0 3478 turn.example.com.
_turns._tcp IN SRV 0 0 5349 turn.example.com.
Note : All the tools should be run from the main folder.
Meaning that every tool should be called using
./tools/tool_name.sh syntax from a shell.
In the following examples, you should replace matrix.yourdomain.com
and turn.yourdomain.com
, by the domain names that will be used to
reach your Matrix Synapse server and your CoTURN server, respectively.
Example :
- If your Matrix domain name is : matrix.hamsters.dev
- If your TURN domain name is : turn.hamsters.dev
Then :
- Replace references to matrix.yourdomain.com by matrix.hamsters.dev
- Replace references to turn.yourdomain.com by turn.hamsters.dev
If you already have SSL certificates, put in them in the ssl/matrix.yourdomain.com and ssl/turn.yourdomain.com and be sure to follow this convention :
fullchain.pem
is a certificate containing the whole chain of trust.key.pem
is the private key associated with your certificate.
If you don't have SSL certificates, you can generate them using tools/letsencrypt-generate.sh.
./tools/letsencrypt-generate.sh matrix.yourdomain.com turn.yourdomain.com
OR
./tools/letsencrypt-generate.sh matrix.yourdomain.com
./tools/letsencrypt-generate.sh turn.yourdomain.com
./tools/docker-prepare.sh matrix.yourdomain.com turn.yourdomain.com
You can setup environment variables to control the generation of some configuration parameters :
- POSTGRESQL_PASSWORD controls the password for PostgreSQL
- TURN_USERNAME controls the username used for TURN
- TURN_PASSWORD controls the password used for TURN
Example :
POSTGRESQL_PASSWORD=W1llBr34kEasily TURN_USERNAME=John TURN_PASSWORD=Piano ./tools/docker-prepare.sh matrix.yourdomain.com turn.yourdomain.com
You can also only setup the desired variables :
TURN_USERNAME=John ./tools/docker-prepare.sh matrix.yourdomain.com turn.yourdomain.com
In such case, the others parameters will be automatically generated.
./tools/riot-install.sh
docker-compose up -d
This is the only script that is installed in the main folder.
This script is generated by tools/docker-prepare.sh
./turn_add_missing_user.sh
./tools/synapse_add_user.sh Username Password
You can then use docker-compose logs
to get the logs of every
units at once, or :
docker-compose logs --last=50 -f matrix
to follow Synapse logsdocker-compose logs --last=5 -f coturn
to follow COTURN logsdocker-compose logs -f postgresql
to follow PostgreSQL logs- See files in
nginx/logs
for NGINX logs
HAProxy logs can be read using : journalctl -t haproxy
HAProxy logs are actually routed to /dev/log which is read by SystemD
journalctl
on most Linux systems.
If you're not using SystemD, you'll have to know where /dev/log is routed (/var/log/messages
?).
- From this repo, run :
docker-compose down
If you generated the Let's Encrypt SSL certificates using the method described in this document, here's how you can renew your certificates.
Execute the following commands while docker-compose is up
:
docker run -v $PWD/letsencrypt:/etc/letsencrypt -v $PWD/static/:/var/lib/letsencrypt certbot/certbot:latest renew
cp -rL letsencrypt/live/* ssl/
cd ssl/matrix.yourdomain.com
cat fullchain.pem privkey.pem > complete.pem
cd -
docker-compose kill -s SIGHUP haproxy # Tell HAProxy to reread its config and the SSL certificates
Used to manage SSL certificates directly and filter out bad traffic, before redirecting it to either Synapse or NGINX
- haproxy/conf/haproxy.cfg
Only used to serve Let's Encrypt ACME challenges and the .well-known/matrix/server file in this setup.
- nginx/conf/nginx.conf
Used to help VOIP users setup their firewalls in order to communicate directly.
In this setup, COTURN uses the host network in order to avoid dealing with Docker "port-ranges" mapping.
Turns out that if you ask Docker to NAT ports between 49000 and 65535 to your container, Docker will setup one
iptables
rule PER PORT !
So if you want to map ports using the 'ports' directive, you'll have to wait patiently for Docker to setup roughly 16000iptables
rules !
Using the Docker host avoid this issue.
- coturn/conf/turnserver.conf
- coturn/conf/turndb
The original form of coturn/conf/turndb
- coturn/conf/turndb_sample
sqlite3 coturn/data/turndb "select * from turnusers_lt"
Execute docker volume inspect pgdata
and check the folder
pointed by "Mountpoint".
Main configuration files :
- synapse/conf/homeserver.yaml
- synapse/conf/homeserver.d/database.yaml
- synapse/conf/homeserver.d/registration.yaml
- synapse/conf/homeserver.d/voip.yaml
Sample configuration with comments :
- synapse/conf/homeserver.yaml.sample
Keys generated by Synapse. I have no idea about how this is used.
- synapse/conf/keys
Data (avatars, files, ...) of your server :
- synapse/data
The Chat client used to connect to your Chat server.
You can still use https://riot.im client though.
Main configuration file :
- static/config.json
Sample configuration file :
- static/config.sample.json
Now untested...
Quite a long-ride for a "quick" setup...
If you don't have SSL certificates, generate free Let's Encrypt SSL
certificates before hand.
To do that you can use the method described below.
docker-compose.yml
is currently configured to use
ssl/matrix.yourdomain.com/... for SSL files related to your Matrix
domain and ssl/turn.yourdomain.com/... for SSL files related to
your TURN domain.
The Checklist follows this logic.
If you use the same SSL certificates for both TURN and Matrix domains,
replace these references accordingly in docker-compose.yml
.
fullchain.pem
is a certificate containing the whole chain of trust.key.pem
is the private key associated with your certificate.complete.pem
is the concatenation offullchain.pem
andkey.pem
If you change any of these filenames, remember to change them in the various configuration files.
This is the only time we map NGINX directly to port 80. In the current setup, HAProxy is mapped to port 80 and handle HTTP connections.
docker-compose down # Shut down all services for the moment
mkdir -p ssl # Be sure that ssl/ exist
docker-compose run -p 80:80 -d nginx # Run only NGINX on port 80 for ACME challenges
For Matrix
export SSL_DOMAIN=matrix.yourdomain.com
docker run -v $PWD/letsencrypt:/etc/letsencrypt -v $PWD/static/:/var/lib/letsencrypt certbot/certbot:latest certonly --agree-tos --email yourmail@yourdomain.com --webroot -w /var/lib/letsencrypt -d $SSL_DOMAIN
cp -rL letsencrypt/live/$SSL_DOMAIN ssl/
For TURN
export SSL_DOMAIN=turn.yourdomain.com
docker run -v $PWD/letsencrypt:/etc/letsencrypt -v $PWD/static/:/var/lib/letsencrypt certbot/certbot:latest certonly --agree-tos --email yourmail@yourdomain.com --webroot -w /var/lib/letsencrypt -d $SSL_DOMAIN
cp -rL letsencrypt/live/$SSL_DOMAIN ssl/
docker-compose down
If you generated SSL certificates yourself, using another method :
- Create the folder ssl/matrix.mynewchat.com/
- Copy SSL certificates for
matrix.mynewchat.com
to ssl/matrix.mynewchat.com/ - Create the folder ssl/turn.mynewchat.com/
- Copy SSL certificates for
turn.mynewchat.com
to ssl/turn.mynewchat.com
cd ssl/matrix.yourdomain.com
cat fullchain.pem privkey.pem > complete.pem
cd -
If you don't do this now, when starting HAProxy through docker-compose, a folder ssl/matrix.yourdomain.com/complete.pem will be created automatically by Docker.
In such case, remove the ssl/matrix.yourdomain.com/complete.pem folder, thencat
the files.
- Edit env/postgres.env and setup the credentials you would like to use for this server instance.
The PostgreSQL instance should NOT be accessible from the outside though, unless you understand what you're doing.
Let's say that :
-
your new domain name for your Matrix server is
matrix.mynewchat.com
-
your new domain name for your TURN server is
turn.mynewchat.com
-
Fork this repository
-
Clone it
git clone https://github.com/YourUserName/matrix-coturn-docker-setup --depth 1
-
In static/.well-known/matrix/server change occurences of
matrix.yourdomain.com
tomatrix.mynewchat.com
-
In static/config.json change occurences of
matrix.yourdomain.com
tomatrix.mynewchat.com
-
In docker-compose.yml change occurences of
matrix.yourdomain.com
tomatrix.mynewchat.com
-
In nginx/conf/nginx.conf change occurences of
matrix.yourdomain.com
tomatrix.mynewchat.com
-
In haproxy/conf/haproxy.cfg change occurences of
matrix.yourdomain.com
tomatrix.mynewchat.com
-
In docker-compose.yml change occurences of
turn.yourdomain.com
toturn.mynewchat.com
-
In coturn/conf/turnserver.conf change occurences of
turn.yourdomain.com
toturn.mynewchat.com
-
In docker-compose.yml edit the following properties, based on your preferences, by modifying the part after the '='. Avoid using quotes in the environment variables :
-
- SYNAPSE_REPORT_STATS=yes # Can be set to "no"
-
- SYNAPSE_VOIP_TURN_USERNAME=turn_username
-
- SYNAPSE_VOIP_TURN_PASSWORD=turn_password
-
-
Download a Riot-web release from their webpage https://github.com/vector-im/riot-web/releases
-
Extract the archive and move all the content from riot-vx.y.z to static/
- From this repo, run :
docker-compose up -d
docker-compose exec synapse register_new_matrix_user -c /etc/synapse/homeserver.d/registration.yaml -u chat_user -p chat_password -a http://localhost:8008
docker-compose exec coturn turnadmin -a -b "/srv/coturn/turndb" -u turn_username -p turn_password -r turn.yourdomain.com
TURN is used to help the users wanting to do direct VOIP
configure their firewalls, and NAT setup.
This remove the complexity of VOIP communications, without
requiring a middleman server (who could record the entire
session).
If
SYNAPSE_VOIP_TURN_USERNAME
is not set to an empty string in the matrix configuration part, the user should be added ASAP, else CoTURN will reject the authentication request and fail VOIP setups.