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

Build a cyber cabin for unrestricted communication among friends 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, besides 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 Island (vfly2.com)

Control end applicable systems: mainstream Linux distributions; this article uses Debian, and non-Debian systems can also be adjusted slightly in Ansible.
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 deploying with Docker manually, and the 443 port will be occupied, which requires a certain level of technical skill to reuse.

It is recommended that the memory of the controlled end be no less than 2GB; by referring to the documentation, reducing the service to 1GB is barely feasible. 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 get through this process, adding other components is just a matter of looking at 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" is mentioned, 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 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 is optional, 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 is also acceptable, 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 they are not occupied by other programs:
1. 80/tcp: HTTP web server
2. 443/tcp: HTTPS web server
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 web server.
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

Download Playbook on Control End#

Create a directory (using ~/Projects here) 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 (to place 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 of logging in with a password 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. If it works, you can gradually add other components, etc.

You need to modify:

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, using the Synapse implementation here
# More options can be found in roles/custom/matrix-base/defaults/main.yml
# For specific instructions, see 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 base key for generating multiple other passwords
# Can be any string, recommended to use openssl rand -base64 48 to generate a 64-bit string
matrix_homeserver_generic_secret_key: 'Wddx05J0Tty9R1M7fzw2nEdR1U9wtGh61+wm3T4SUQi2IbtF2roi6VfqSrMzfKJc'

# The default is to use Traefik for reverse proxy, which can automatically apply for 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 certificates
# More instructions: docs/configuring-playbook-ssl-certificates.md
devture_traefik_config_certificatesResolvers_acme_email: '[email protected]'

# The superuser for Postgres is matrix, set its password here
# 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 registration invitation codes
# 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 instruct 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 at this step.

Install 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 is executed, you can actually open the web version, register users, and 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 configures it automatically.

(important) Federation Server discovery

Assists other instances in discovering themselves; without proper configuration, they cannot join the federation or establish connections with other federation members. However, single-machine usage 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, etc., or even manually copy the content to a new file to make it publicly available on the web server.

(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 detection.

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 those codes.

For more methods, see 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 Island (vfly2.com)

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, licensed under CC BY-NC-SA 4.0 unless otherwise stated. Please indicate the source when reprinting: Technique Island (technique.vfly2.com).

Stay updated ٩(•̤̀ᵕ•̤́๑)ᵒᵏᵎᵎᵎᵎ with clear and practical skills. You are welcome to subscribe using 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 join the Telegram group https://t.me/vfly2 to discuss any issues encountered during the article's steps.