My matrix homeserver
Go to file
2024-05-22 04:27:47 +03:00
data chore(email): Enable server to sending emails 2024-05-22 04:27:47 +03:00
docker-compose.yml Make the UID and GID to 1000 (first user) 2024-05-03 15:14:44 +03:00
generate_signing_key first commit 2024-04-13 17:33:38 +03:00
Justfile Support database backup and restore 2024-05-03 13:26:46 +03:00
LICENSE first commit 2024-04-13 17:33:38 +03:00 Update 2024-05-03 13:26:46 +03:00

4rs matrix homeserver

This is my personal matrix homeserver. You can clone this repository and run the homeserver with docker-compose.


In this repository I use (my domain) as an example. You should replace this with your own domain. After reading this README you should have a /.well-known/matrix/server and /.well-known/matrix/client file on your domain ( The client will use as the homeserver and the displayed server name will be


  • docker
  • docker-compose
  • nginx

Domain requirements

  • Have a /.well-known/matrix/server file on your domain (server name) that points to your homeserver. This is required for federation to work. The content of the file should be:
    "m.server": ""
  • Have a /.well-known/matrix/client file on your domain (server name) that points to your homeserver. This is required for the client to work. The content of the file should be:
    "m.homeserver": {
        "base_url": ""

For me, I created the files in my static blog and then deployed it in GitHub pages. See the files here in my blog repository. You can use any other method to deploy the files and make them accessible on your domain, as long as they are accessible at /.well-known/matrix/server and /.well-known/matrix/client.

Nginx configuration of the matrix subdomain

You should have a nginx configuration for the matrix subdomain at /etc/nginx/sites-available/ and symlinked to /etc/nginx/sites-enabled/, Also include it in the nginx.conf file with include /etc/nginx/sites-enabled/*; (the include is already in the nginx.conf file when you install nginx).

You also need to have a certificate for the domain. You can get a free certificate from Let's Encrypt. You can use Certbot to get a certificate. (Generate a certificate for and *

The configuration should look like this (replace with your domain)

server {
    listen         80;
    listen         [::]:80;
    location / {
      return         301 https://$server_name$request_uri;

server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    access_log  /var/log/nginx/access.log;
    error_log /var/log/nginx/error.log warn;

    ssl_session_timeout 1d;
    ssl_session_cache shared:MozSSL:10m;
    ssl_session_tickets off;

    ssl_trusted_certificate   /etc/letsencrypt/live/;
    ssl_certificate           /etc/letsencrypt/live/;
    ssl_certificate_key       /etc/letsencrypt/live/;

    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_prefer_server_ciphers off;
    ssl_stapling on;
    ssl_stapling_verify on;

    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_buffers 16 8k;
    gzip_http_version 1.1;
    gzip_types text/plain text/css application/json application/javascript text/xml application/xml application/xml+rss text/javascript application/activity+json application/atom+xml;

    ignore_invalid_headers off;

    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $http_host;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;

    client_body_timeout 5s;
    client_header_timeout 5s;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;
        client_max_body_size 200M;

After you have created the configuration file, reload nginx with sudo systemctl reload nginx. You should now be able to access the homeserver at

Now you end up the Nginx configuration for the matrix subdomain. The next step is to clone this repository and run the homeserver.

Clone the repository

After you have set up the domain and the nginx configuration, you can clone this repository with git clone You should now have a directory called synapse-config.


After you have cloned the repository, replace all with your domain also the files in the ./data directory.

There is tow things only you need to change it, the first one is the secrets in ./data/homeserver.yaml and the second one is the signing key in ./data/


After replacing all with your domain, you need to generate a secret for each secret in the homeserver.yaml file. You can generate a secret with openssl rand -base64 32. Replace the secret with the generated secret.

Signing key


You need signedjson dependency to generate a signing key. You can install it with pip3 install signedjson.

Change the content of the file with a generated key. You can generate a key with generate_signing_key script in root of the repository. Run python3 generate_signing_key and replace the content of the file with the generated key.

Run the homeserver and create the admin user

After all above steps, you can run the homeserver with docker-compose up -d. You should now have a running homeserver on

Now you need to create an admin user with docker exec -it synapse register_new_matrix_user http://localhost:8008 -c /data/homeserver.yaml and follow the instructions. You should now have an admin user on the homeserver and you can login with it on the client using the homeserver Enjoy your homeserver!


You need just to backup and restore your homeserver. You can install it with cargo install just.


You can backup the homeserver with just backup <backup-name>. And it's will stored as encrypted AES256 7z file.


To restore the homeserver, you can use just restore <backup-name>. Make sure to run it in the root of the repository.

Any questions?

If you have any questions, you can contact with me at and I will try to help you. Have fun with your homeserver!