Matrix is a project to create a decentralized chat / messaging world. Probably much more than that, but i think it's the definitive and only future-proof messaging solution.

It looks amazing and it already has so many features that can replace other proprietary solutions. Unfortunately, it is still quite difficult not only to setup, but also to use. One of the big selling point, in my opinion, are the bridges to the other messaging solutions, but the lack of a really viable whatsapp bridge is a bummer. The reason is due to whatsapp limitation, but i am not ready to give up my main whatsapp account on my phone to move it to a VM running on my server.

The Telegram integration works pretty well, even if the initial setup proved to be a bit shaky, it's solid after that phase. I didnt explore any other bridge at the moment.

Overall i am not yet sure if the effort is worthwile, but since i believe in the need for an open internet, i will give Matrix more time.

Matrix is the high-level protocol. To join, or host, a Matrix network you need a Matrix server implementation. There are quite a few but i choose Synapse because it's solid and well-proven.

In addition to the server itself, you need the bridges if you want to connect your matrix instance to other messaging platforms. I only use Telegram and Whatsapp (well, discord maybe, but it's more of a forum for me than an actual messaging tool), and of these only Telegram has a viable bridge.

More info about the bridges can be found here.

To use Matrix properly you do need one dedicated subdomain. It is teorically possible to host on sub-paths, but i do not recomend it as it adds another layer of uncertainity and complexity that you don't want. I will assume you have https://chat.mydomain.com for your Matrix service. Also note that https is mandatory.

It is possible to install Synapse and the Telegram bridge on bare-metal leveraging Python Virtual Envs, but unless you want to use a SQLite (which won't scale easily) database, you will also need a PostgresSQL installation.

Overall, i prefer to go the container route which proved to be easy enough. Setting up and running properly your Matrix instance is already tricky that adding a bare-metal installation hurdle didnt seems needed.

As usual create one dedicated user, and create a data folder where all the data will be stored:

useradd -d /data/daemons/synapse -m synapse
mkdir /data/synapse
mkdir /data/synapse/data
mkdir /data/synapse/database
mkdir /data/synapse/bridges
mkdir /data/synapse/bridges/telegram
chown synapse:synapse -R /data/synapse

The data folder will contain Synapse configuration and uploaded files. The database folder will contain the PostgreSQL database. The bridges folders will contain each one bridge various files.

Now, take the following docker-compose.yml file and adapt to your needs:

docker-composer.yml

version: '3.7'
services:
  synapse:
    image: docker.io/matrixdotorg/synapse:latest
    restart: unless-stopped
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
    volumes:
      - /data/synapse/data:/data
    depends_on:
      - db
    ports:
      - 8008:8008/tcp
    networks:
      - synapse-net

  mautrix-telegram:
    container_name: mautrix-telegram
    image: dock.mau.dev/mautrix/telegram:latest
    restart: unless-stopped
    depends_on:
      - db
    volumes:
    - /data/synapse/bridges/telegram:/data
    networks:
      - synapse-net
  db:
    image: docker.io/postgres:12-alpine
    # Change that password, of course!
    environment:
      - POSTGRES_USER=synapse
      - POSTGRES_PASSWORD=<<< my db password >>>
      - POSTGRES_INITDB_ARGS=--encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - /data/synapse/database:/var/lib/postgresql/data
    networks:
      - synapse-net

networks:
  synapse-net: {}

Now, as usual, pull the images:

podman compose pull

Generate initial configuration file:

podman compose run --rm -e SYNAPSE_SERVER_NAME=chat.mydomain.com -e SYNAPSE_REPORT_STATS=yes synapse generate

Edit your /data/synapse/data/homeserver.yaml so that you use PostgresSQL, and double check the paths and server name:

homeserver.yaml

server_name: "chat.mydomain.com"
pid_file: /data/homeserver.pid
# NOTE: enable the following two lines ONLY to create users, then REMOVE them!
#enable_registration: true
#enable_registration_without_verification: true
listeners:
  - port: 8008
    tls: false
    type: http
    x_forwarded: true
    resources:
      - names: [client, federation]
        compress: false
database:
  name: psycopg2
  args:
    user: synapse
    password: <<< my db password >>>
    dbname: synapse
    host: db
    cp_min: 5
    cp_max: 10
log_config: "/data/chat.mydomain.com.log.config"
media_store_path: /data/media_store
registration_shared_secret: "<<< random secret >>>"
report_stats: true
macaroon_secret_key: "<<< random key >>>"
form_secret: "<<< random secret >>>"
signing_key_path: "/data/chat.mydomain.com.signing.key"
trusted_key_servers:
  - server_name: "matrix.org"

At this point, you are ready to run the Matrix.

The main docker-compose.yml above already contains the bridge image, so just run it once to have it create all the files under */data/synapse/bridges/telegram, and then edit the main file: …

Edit the file /data/synapse/bridges/telegram/config.yaml and will in all the required details.

Go to https://my.telegram.org/apps| and generate both an api_id and api_hash. Optionally you can go to the BotFather in Telegram and create a specific bot for you (here)

Some hints on config.yaml:

• homeserver - address: the URL of your instance (https://chat.mydomain.com)
• homeserver - domain: the URL of your instance, cleaned (chat.mydomain.com, yes, this is not a typo)
• appservice - address: the container name of the bridge (so, http://mautrix-telegram:29317)
• appservice - database: i had to switch to SQLite, as i couldn't create a PostgresSQL new database (so, database: sqlite:/data/mautrix-telegram.db)
• permissions: change to match your admin user and instance name (ex: chat.mydomain.com: full \n '@admin:chat.mydomain.com': admin)
• telegram - api_id the API_ID generated on telegram
• telegram - api_hash: API_HASH generated on telegram
• telegram - bot_token: the bot token created on telegram (optional)

Copy the /data/synapse/bridges/telegram/registration.yaml to /data/synapse/data/mautrix-telegram-registration.yaml. If the file is missing, restart the containers to have it generated. If you change anything inside the config.yaml, delete the registration.yaml and restart the containers.

It is very important to note that the registration.yaml file must be correct and copied to the synapse data folder. This is mandatory to let the TelegramBot authenticate in Synapse, and if the bridge does not work, you need to double check that the contents of this file looks correct and match you actual configuration.

You need to run your Matrix behind a reverse proxy so that you can easily add SSL and protect your server. See The Reverse Proxy concept for more details.

This is a simple and effective chat.conf for NGINX:

chat.conf

server {
        server_name chat.mydomain.com;
        listen 8443 ssl; 
        listen 443 ssl; 

        access_log /var/log/nginx/chat.mydomain.com_access_log main;
        error_log /var/log/nginx/chat.mydomain.com_error_log info;

        location ~ ^(/_matrix|/_synapse/client) {
                # note: do not add a path (even a single /) after the port in `proxy_pass`,
                # otherwise nginx will canonicalise the URI and cause signature verification
                # errors.
                proxy_pass http://127.0.0.1:8008;
                proxy_set_header X-Forwarded-For $remote_addr;
                proxy_set_header X-Forwarded-Proto $scheme;
                proxy_set_header Host $host;

                # Nginx by default only allows file uploads up to 1M in size
                # Increase client_max_body_size to match max_upload_size defined in homeserver.yaml
                client_max_body_size 500M;

        # Synapse responses may be chunked, which is an HTTP/1.1 feature.
        proxy_http_version 1.1;
        }
        include com.mydomain/certbot.conf;
}

If you are following my Custom User Services approach, it's pretty easy:

cd /etc/local.d
ln -s _servicer.sh 63-synapse--podman.start
ln -s _servicer.sh 63-synapse--podman.stop

One of the not so intuitive things about Matrix is user creation. I didnt waste too much time on this because i only needed two users (and in general, only a limited numnber of family members), so i went the manual way.

After starting the containers, as user synapse, run:

podman compose run --rm --entrypoint /bin/bash synapse
/usr/local/bin/register_new_matrix_user https://chat.mydomain.com  -c /data/homeserver.yaml