Automatically install the Matrix instant messaging network using Ansible for free and unrestricted communication.

Build a cyber cabin for friends to communicate freely and without restrictions, without worrying about any surveillance or censorship.

Matrix is a protocol with different implementations. It works similarly to email, featuring "decentralization" and "end-to-end encryption."

Server implementations (as long as they follow the Matrix protocol, any implementation can communicate with each other):
- Established Synapse: Synapse: Matrix homeserver written in Python/Twisted. (github.com)
- Emerging Conduit: Conduit - Your own chat server
Client implementations
- Recommended Element, supports all platforms
- The iOS client in the Chinese region is not very good; you can temporarily use Hydrogen in the browser.

In addition, through bridge components, you can communicate with other platforms on the Matrix network, such as Telegram and E-mail.

Finally, in addition to basic text sending, you can also make voice calls and video chats. You can install the Jitsi video conferencing platform, Etherpad open-source collaborative text editor, etc.

This article focuses on the deployment process. For introduction and specific usage methods, please visit: Self-hosted Instant Messaging - A Cyber Cabin for Free and Unrestricted Communication Under Comprehensive Supervision - Technique Vfly2

Control end applicable systems: mainstream Linux distributions, this article uses Debian system; for non-Debian systems, slight adjustments in Ansible can also work.
Controlled end applicable systems: mainstream Linux distributions

Estimated time to complete: 60 minutes

This matrix-docker-ansible-deploy project uses Ansible to set up a Matrix server on the controlled end using Docker containers, so there is no need to perform these tasks manually. The operation is simple and hassle-free; however, memory usage is slightly higher than manual Docker deployment, and port 443 will be occupied, which requires a certain level of technical skill to reuse.

It is not recommended for the controlled end to have less than 2GB of memory; reducing the service to 1GB is barely feasible according to documentation. After the initial configuration, the first installation generally takes about 20 minutes.

In fact, the specifications of the server required largely depend on your instance and how many large rooms (thousands of people) it will connect to, rather than the number of users.

Under this article's process, the actual installation project:

Server: Synapse
Client: Element's web version

Keep it simple; once you can complete this process, adding other components is just a matter of checking the documentation and adding a few lines of configuration.

Preparations#

For simplicity, use root to control the controlled end and connect via SSH with a password, so ensure that SSH on the controlled end allows root login.

Below, if "server" appears, it refers to the "controlled end," and Ansible is installed on the "control end," which can be on a local computer or on a server.

Configure DNS Resolution for the Domain#

Taking the domain vfly2.com as an example, please modify it to your actual domain during practical operation.

If using Cloudflare DNS, ensure it is set to DNS only.

Basics:

A record for vfly2.com pointing to the server IP (this can be skipped, but you will need to manually set up reverse proxy later).
A record for matrix.vfly2.com pointing to the server IP.
CNAME record for element.vfly2.com pointing to matrix.vfly2.com (an A record can also be used, but CNAME is more convenient for future server migrations).

Controlled End#

It is recommended to use the latest Debian system, preferably a freshly installed system.
Able to log in as root or have sudo privileges (this article requires root login).
Python3 and pip installed: apt install python3 python3-pip -y.
Ensure the firewall opens the following ports or that the ports are not occupied by other programs:
1. 80/tcp: HTTP webserver
2. 443/tcp: HTTPS webserver
3. 3478: TURN over TCP/UDP (used by Coturn)
4. 5349: TURN over TCP/UDP (used by Coturn)
5. 8448/tcp: Matrix Federation API HTTPS webserver.
6. the range 49152-49172/udp: TURN over UDP

Control End#

You can install Ansible on another Linux server as the control end and operate as a regular user; this article follows this model.

Control end requirements:

Git installed, which is generally available.
Just installed (it is a make-type tool, easier to use).
Ansible and PassLib library installed.

Install Just:

sudo -i   # Switch to root

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | sudo bash -s -- --to /usr/local/bin

just --help   # Check if the installation was successful

Install Ansible:

python3 -m pip install --user ansible
ansible --version
# At this point, Ansible is installed in ~/.local/bin/ansible

Install PassLib:

python3 -m pip install --user passlib

Control End Download Playbook#

Create a directory (here using ~/Projects) to place the Playbook:

mkdir ~/Projects && cd ~/Projects && \
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git

This will create a directory named matrix-docker-ansible-deploy, and all subsequent operations will be performed in this directory.

Custom Configuration File#

Create a directory (for placing custom configurations):

mkdir inventory/host_vars/matrix.vfly2.com

Copy sample files and host files:

cp examples/vars.yml inventory/host_vars/matrix.vfly2.com/vars.yml
cp examples/hosts inventory/hosts   # Contains connection information for the controlled end

Edit the host file:

vim inventory/hosts

Place the controlled end information in it so that Ansible can log in to control it. An example for password login is as follows:

[matrix_servers]
matrix.vfly2.com ansible_host=<ip> ansible_ssh_user=root ansible_ssh_pass=<user_password> ansible_ssh_port=<ssh_port>

Customize the configuration file (refer to the sample below):

vim inventory/host_vars/matrix.vfly2.com/vars.yml

Configuration File Sample#

It is recommended to first use the configuration file below to go through the process. If successful, you can gradually add other components.

Required modifications:

matrix_domain
matrix_homeserver_generic_secret_key
devture_traefik_config_certificatesResolvers_acme_email
devture_postgres_connection_password

---
# Bare domain for user ID
# If filled incorrectly, you can only uninstall and reinstall
matrix_domain: vfly2.com

# The Matrix server to be installed, here using the Synapse implementation
# More options can be found in roles/custom/matrix-base/defaults/main.yml
# For specific instructions, refer to docs/configuring-playbook-IMPLEMENTATION_NAME.md
matrix_homeserver_implementation: synapse

# Some settings for Synapse
# Default settings in roles/custom/matrix-synapse/defaults/main.yml
# Allow registration
matrix_synapse_enable_registration: true
# Registration requires an invitation code
matrix_synapse_registration_requires_token: true

# A basic key used to generate multiple other passwords
# Can be any string, recommended to use openssl rand -base64 48 to generate a 64-character string
matrix_homeserver_generic_secret_key: 'Wddx05J0Tty9R1M7fzw2nEdR1U9wtGh61+wm3T4SUQi2IbtF2roi6VfqSrMzfKJc'

# By default, Traefik is used for reverse proxy, which can automatically request SSL certificates and automate reverse proxy components
# For other alternatives, see `docs/configuring-playbook-own-webserver.md`.
matrix_playbook_reverse_proxy_type: playbook-managed-traefik

# Email used to apply for Let's Encrypt issued certificates
# More details: docs/configuring-playbook-ssl-certificates.md
devture_traefik_config_certificatesResolvers_acme_email: '[email protected]'

# The superuser for Postgres is matrix, here set its password
# This playbook will create a user and database for each component, executed by the matrix user
devture_postgres_connection_password: '9HwDqeQ/ZzRlRyaH7KsjW0Q7mEwO7t52YrIsiRUzFieDmvfJ6U4aiMMcrU/5Hdsq'

# Install the synapse_admin component, which is a backend to view users and add invitation codes for registration
# It does not require a separate domain setting; the URL is https://matrix.vfly2.com/synapse-admin/
matrix_synapse_admin_enabled: true

Formal Installation#

# All operations are performed in this directory
cd ~/Projects/matrix-docker-ansible-deploy

To log in with a password, you need to install sshpass:

sudo apt install sshpass

You also need to log in manually once:

ssh -p 22 [email protected]

Before installation, including after updating the playbook or configuration files, you need to update Ansible roles, which dictate how to operate the controlled end.

just roles   # Yes, just run this command

If you are migrating an old instance, you can follow the migration part of the process from this step.

Installing on a New Machine#

Completely install and start all Matrix services:

ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start

After this command completes, you can actually open the web version, and after registering a user, you can start using it.

Mutual Discovery#

Configure to enable mutual discovery between federations. If the bare domain vfly2.com is directly resolved to the server, this section can be ignored, as the playbook has configured it automatically.

(important) Federation Server discovery

Assists other instances in discovering themselves; without correct configuration, they cannot join the federation or establish connections with other federation members. However, single-machine use is unaffected.

This refers to whether the content of the webpage https://<matrix_domain>/.well-known/matrix/server is normal.

This playbook installs the instance on another domain (for example, this article uses matrix.vfly2.com) rather than on the base domain (vfly2.com), but the Matrix protocol itself requires discovery at the base domain.

The content of the instance installed using this playbook is here: https://matrix.vfly2.com/.well-known/matrix/server, and the content is:

{
    "m.server": "matrix.vfly2.com:8448"
}

Just ensure that the content accessed at https://vfly2.com/.well-known/matrix/server is the same as above. You can use reverse proxy, or even manually copy the content to a new file and let the web server expose it.

(not that important) Client Server discovery

Assists your own client in discovering the server it connects to, making it easier to query users.

This refers to whether the content of the webpage https://<matrix_domain>/.well-known/matrix/client is normal.

Same as above.

Check if the Service is Working Properly#

ansible-playbook -i inventory/hosts setup.yml --tags=self-check

You can also use the Federation Tester for testing.

Create Users#

Adding users through the management backend is the simplest method. If you installed according to the configuration sample above, you can access the backend at https://<domain>/synapse-admin/ to create users directly.

The backend can also generate invitation codes, allowing others to register using the codes.

For more methods, refer to the official documentation: https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/registering-users.md

Since you have self-hosted Matrix, how can you not maintain Matrix? For backing up and migrating the Matrix installed using Ansible in this article: Matrix Maintenance: Backup and Migration - Technique Vfly2

Original link: https://technique.vfly2.com/2024/01/automated-installation-of-matrix-using-ansible/

Copyright statement: All articles on this blog are original works by AhFei, unless otherwise stated, and are licensed under CC BY-NC-SA 4.0. Please indicate the source when reprinting Technique Vfly2 (technique.vfly2.com).

Stay updated ٩(•̤̀ᵕ•̤́๑)ᵒᵏᵎᵎᵎᵎ with clear and practical skills. You are welcome to subscribe via RSS or follow @[email protected] on platforms supporting ActivityPub to receive new article notifications. It would be even better if you could leave comments and interact.

You can discuss any issues encountered during the article's steps in the Telegram group https://t.me/vfly2.