How to install Matrix-docker-ansible | Decentralised Communication

Introduction

Overview of Matrix and Its Benefits

Matrix is an open-source, decentralized communication protocol designed for secure, real-time messaging and collaboration. It powers popular chat applications like Element and allows users to communicate across different platforms while maintaining privacy and security.

Unlike centralized messaging apps like WhatsApp or Slack, Matrix offers greater control by enabling individuals and organizations to host their own servers. This ensures:

• Data Privacy – Your messages stay on your own server, not a third-party cloud.
• Decentralization – No single company controls Matrix; it’s a network of independent servers.
• Federation – Matrix servers can communicate with each other, just like email.
• End-to-End Encryption – Ensures private and secure communication.
• Extensibility – Can integrate with other platforms like Slack, Discord, and Telegram.

Because of these benefits, Matrix is widely used by developers, businesses, activists, and privacy-conscious users who want more control over their communication platforms.

Why Use Ansible for Deployment?

Installing and configuring a Matrix server manually can be complex, especially for beginners. Ansible, an automation tool, simplifies this process by automating server setup, configuration, and deployment.

Here’s why Ansible is the best choice for deploying Matrix:

• Time-Saving – Automates repetitive tasks, reducing installation time.
• Error-Free Deployment – Ensures consistency across servers with predefined scripts.
• Easier Updates – Allows smooth upgrades and reconfigurations without breaking the setup.
• Scalability – Can manage multiple servers at once, making it ideal for large deployments.
• Minimal Technical Knowledge Required – Even non-experts can follow the playbook and set up Matrix.

By using Ansible with the Matrix Docker-Ansible-Deploy playbook, even users with little technical expertise can deploy a fully functional, self-hosted Matrix server with minimal effort.

Prerequisites

Requirements for Local Computer

Before installing Matrix on your server, you need to set up a few essential tools on your local computer. These tools help you run the Ansible playbook, which automates the installation process.

Installing Ansible

Ansible is the core tool used to deploy Matrix on your server. It automates the setup process, ensuring that everything is installed correctly without requiring manual configurations.

To install Ansible on your computer, use the following command:

sudo apt update && sudo apt install ansible -y

This command:

• Updates the package list
• Installs Ansible along with necessary dependencies

For Mac users, Ansible can be installed using Homebrew:

brew install ansible

Checking Ansible Version

Once Ansible is installed, you need to verify that it’s installed correctly and meets the required version.

Run the following command to check the version:

ansible --version

The output will display the installed Ansible version along with details like configuration file location and Python interpreter. Make sure it meets the playbook’s requirements.

Installing Python and Passlib

Ansible relies on Python, so you need to install it along with Passlib, a library required for password hashing.

Step 1: Install Python and Pip

Use the following command to install Python and Pip (Python’s package manager):

sudo apt install python3 python3-pip -y

Step 2: Install Passlib

Once Python is installed, you need to install Passlib, which is required for managing authentication securely:

pip install passlib

Tip: If you face permission errors, try adding --user at the end of the command:

pip install --user passlib

Installing Git

Git is required to download the Matrix Ansible playbook from its official repository.

To install Git, run:

sudo apt install git -y

After installation, verify that Git is installed correctly:

git --version

This will display the installed Git version, confirming that the setup is complete.

Server Requirements

To host a Matrix server successfully, your server must meet certain hardware and software requirements. This ensures smooth performance, security, and compatibility with the Ansible playbook.

Recommended Server Specifications

For optimal performance, your server should have:

• CPU: Minimum 2 vCPUs (4 vCPUs recommended for larger deployments)
• RAM: At least 4GB (8GB+ recommended for heavy usage)
• Storage: Minimum 20GB SSD (More if you plan to store a lot of media files)
• Network: A reliable internet connection with a static IP address

Tip: A dedicated VPS or cloud server (like AWS, DigitalOcean, or Linode) is ideal for hosting Matrix.

Supported Operating Systems

Matrix works best on Linux-based servers. The following OS versions are officially supported:

• Debian 10 (Buster) or newer (Recommended)
• Ubuntu 18.04 or newer (20.04 may have some compatibility issues)
• CentOS, Rocky Linux, AlmaLinux (and other RHEL-based distros)
• Arch Linux

Note:

• Older OS versions may cause compatibility issues.
• If your server runs inside an LXC container, you might face installation issues.

Required Software and Dependencies

• Docker & Docker Compose – The playbook runs Matrix services inside Docker containers. Install them using:

sudo apt install docker.io docker-compose -y

Necessary Firewall and Open Ports

To allow Matrix services to function properly, certain ports must be open in your firewall.

Here’s a list of required ports:

How to Open These Ports on Ubuntu/Debian?

If you are using UFW (Uncomplicated Firewall), open the required ports with:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 5349/tcp
sudo ufw allow 5349/udp
sudo ufw allow 8448/tcp
sudo ufw allow 8448/udp
sudo ufw allow 49152:49172/udp
sudo ufw enable

Tip: If your server is behind a cloud provider firewall (AWS, Google Cloud, Microsoft Azure and Oracle Cloud), open these ports in the provider’s control panel.

Configuring DNS Settings for Matrix Server

To run a self-hosted Matrix server, you need to configure DNS records correctly. These settings ensure that users can connect to your server, access the Element Web client, and enable Matrix Federation (communication between different Matrix servers).

In this section, I’ll guide you through:

• The default DNS records required for your Matrix server
• The subdomains for the Matrix services
• Special considerations when using Cloudflare DNS

Default DNS Records

A properly configured DNS (Domain Name System) ensures that your Matrix services are accessible under your chosen domain name.

At a minimum, you need to set up the following DNS records in your domain registrar’s control panel:

Matrix Server Subdomains

Your Matrix server runs on a subdomain of your main domain.

Example Configuration

If your domain is example.com, then your Matrix server will typically run on:

matrix.example.com (This is where your Matrix homeserver runs)

DNS Setup:

• Create an “A” record in your domain DNS settings.
• Set the Host field to matrix.
• Point it to your server’s IP address.

Why This Is Important?
This configuration ensures that users can register, log in, and send messages using your self-hosted Matrix server.

Element Web Subdomain

Element Web is the web-based Matrix client that users will interact with. By default, the playbook installs Element Web at element.example.com.

Example Configuration

element.example.com (Where the Element Web client is hosted)

DNS Setup:

1. Create a “CNAME” record in your DNS settings.
2. Set the Host field to element.
3. Point it to matrix.example.com.

Why This Is Important?

• This allows users to access the Matrix chat interface via their browser.
• Without this, users would need to manually configure their Element Web settings.

Cloudflare DNS Considerations

If you are using Cloudflare as your DNS provider, there are a few important settings to check:

Disable Cloudflare Proxy for Matrix Records

• Cloudflare’s proxy mode (orange cloud icon) can interfere with Matrix Federation and SSL certificate retrieval.
• Go to Cloudflare DNS settings and set all Matrix-related records to “DNS Only” (gray cloud icon).

How to Disable Cloudflare Proxy?

• Go to Cloudflare Dashboard → DNS Settings
• Find your Matrix-related records (matrix.example.com and element.example.com).
• Click on the orange cloud icon to switch it to gray (DNS Only).

Why This Is Important?

• Cloudflare’s proxy hides your server’s real IP, which breaks SSL certificate validation.
• Matrix Federation requires direct server-to-server communication, which Cloudflare’s proxy can block.

Note:

• DNS changes can take anywhere from a few minutes to 24 hours to fully propagate across the internet.
• You can use any subdomain (e.g., chat.example.com instead of matrix.example.com). Just make sure your DNS records match your Matrix playbook configuration.
• it’s recommended. Matrix services rely on DNS, so setting it up beforehand prevents errors during installation.
• Setting up the correct DNS records ensures seamless Matrix communication.
• Matrix and Element Web need to be properly configured to work together.
• If using Cloudflare, disable the proxy mode to avoid SSL and federation issues.

Now that your DNS is configured, we can move on to the next step: Getting the Playbook!

Installation Matrix Docker Ansible

Getting the Playbook

Before you can install Matrix using Ansible, you need to download the official Matrix Docker-Ansible-Deploy playbook. This playbook contains pre-configured scripts that automate the entire setup process, making installation easy even for beginners.

Why Do You Need the Playbook?

• It contains all the necessary files and configurations to deploy a self-hosted Matrix server.
• It automates complex tasks, reducing the risk of errors.
• It keeps your setup organized and easy to update over time.

Downloading the Playbook

The recommended way to download the playbook is by using Git. This allows you to stay up to date with the latest updates, apply changes easily, and track modifications.

Clone the Playbook Repository

Once Git is installed, you can now download the playbook by cloning the official repository.

Run the following command:

git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git

What Happens Here?

• This command downloads all playbook files into a new folder called matrix-docker-ansible-deploy.
• You now have the latest version of the playbook from GitHub.

Navigate to the Playbook Directory

Once the repository is cloned, move into the directory where the playbook files are stored:

cd matrix-docker-ansible-deploy

This is where all configurations and installation steps will be performed.

Keep the Playbook Updated

Since the Matrix project is actively maintained, regular updates bring security patches and new features.

To update your playbook, run:

cd matrix-docker-ansible-deploy git pull origin main

Why Is This Important?

• Ensures you have the latest bug fixes and security patches.
• Keeps your setup compatible with new Matrix features.

Configuring the Playbook

Once you have downloaded the Matrix Ansible playbook, the next step is to configure it to match your domain, server settings, and security preferences.

This section covers:
Creating configuration files (vars.yml and hosts)
Essential configuration settings (Domain, SSL, Database, Networking)

Properly setting up these files ensures smooth installation and operation of your Matrix server.

Creating Configuration Files

The Matrix playbook requires two main configuration files to be created before running the installation:

vars.yml – Defines your server settings (domain, SSL, database, etc.).
hosts – Specifies which server Ansible should install Matrix on.

Create a Configuration Directory

First, create a directory to store your configuration files:

mkdir -p inventory/host_vars/matrix.example.com
## (Replace example.com with your actual domain name.)

Create and Edit vars.yml

The vars.yml file stores all the key settings for your Matrix deployment.

Copy the sample file to your inventory folder:

cp examples/vars.yml inventory/host_vars/matrix.example.com/vars.yml

Open it in a text editor (like nano) for editing:

nano inventory/host_vars/matrix.example.com/vars.yml

Here’s what a basic vars.yml setup looks like:

---
# The bare domain name which represents your Matrix identity.
# Matrix user IDs for your server will be of the form (`@alice:example.com`).
#
# Note: this playbook does not touch the server referenced here.
# Installation happens on another server ("matrix.example.com", see `matrix_server_fqn_matrix`).
#
# If you've deployed using the wrong domain, you'll have to run the Uninstalling step,
# because you can't change the Domain after deployment.
# matrix_domain: matrix.kliks.online
# This is what your identifiers are like (e.g. `@bob:matrix.example.com`).
matrix_domain: "<matrix-domain>"

# This is where Matrix services
matrix_server_fqn_matrix: "<matrix-domain>"

# This is where you access the Element Web from (if enabled via `matrix_client_element_enabled: true`; enabled by default).
# This and the Matrix FQN (see above) are expected to be on the same server.
#
# Feel free to use `element.matrix.example.com`, if you'd prefer that.
matrix_server_fqn_element: "<element-domain>"

# The Matrix homeserver software to install.
# See:
#  - `roles/custom/matrix-base/defaults/main.yml` for valid options
# - the `docs/configuring-playbook-IMPLEMENTATION_NAME.md` documentation page, if one is available for your implementation choice
#
# By default, we use Synapse, because it's the only full-featured Matrix server at the moment.
#
# Note that the homeserver implementation of a server will not be able to be changed without data loss.
matrix_homeserver_implementation: synapse

# A secret used as a base, for generating various other secrets.
# You can put any string here, but generating a strong one is preferred. You can create one with a command like `pwgen -s 64 1`.
matrix_homeserver_generic_secret_key: "<secret-key>"

# By default, the playbook manages its own Traefik (https://doc.traefik.io/traefik/) reverse-proxy server.
# It will retrieve SSL certificates for you on-demand and forward requests to all other components.
# For alternatives, see `docs/configuring-playbook-own-webserver.md`.
# matrix_coturn_enabled: false
# matrix_coturn_turn_external_ip_address: 54.167.5.52
# matrix_coturn_authentication_method: lt-cred-mech
matrix_playbook_reverse_proxy_type: playbook-managed-traefik

# This is something which is provided to Let's Encrypt when retrieving SSL certificates for domains.
#
# In case SSL renewal fails at some point, you'll also get an email notification there.
#
# If you decide to use another method for managing SSL certificates (different than the default Let's Encrypt),
# you won't be required to define this variable (see `docs/configuring-playbook-ssl-certificates.md`).
#
# Example value: [email protected]
traefik_config_certificatesResolvers_acme_email: "<valid-email-SSL-Certificate>"

# A Postgres password to use for the superuser Postgres user (called `matrix` by default).
#
# The playbook creates additional Postgres users and databases (one for each enabled service)
# using this superuser account.
postgres_connection_password: "<strong-password>"

# By default, we configure Coturn's external IP address using the value specified for `ansible_host` in your `inventory/hosts` file.
# If this value is an external IP address, you can skip this section.
#
# If `ansible_host` is not the server's external IP address, you have 2 choices:
# 1. Uncomment the line below, to allow IP address auto-detection to happen (more on this below)
# 2. Uncomment and adjust the line below to specify an IP address manually
#
# By default, auto-detection will be attempted using the `https://ifconfig.co/json` API.
# Default values for this are specified in `matrix_coturn_turn_external_ip_address_auto_detection_*` variables in the Coturn role
# (see `roles/custom/matrix-coturn/defaults/main.yml`).
#
# If your server has multiple IP addresses, you may define them in another variable which allows a list of addresses.
# Example: `matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '4.5.6.7']`
#
# matrix_coturn_turn_external_ip_address: ''
#matrix_nginx_proxy_base_domain_serving_enabled: true

matrix_client_element_enabled: true
devture_playbook_state_preserver_commit_hash_preservation_enabled: false

Pro Tip:

• Use a randomly generated secret key (pwgen -s 64 1) for security.
• If you don’t control the base domain, additional configuration is needed (explained below).
• Your Matrix identity is tied to your base domain.

## Example Matrix ID
User: @alice:example.com
Server: matrix.example.com

• Make sure “matrix_domain“ and “matrix_server_fqn_element” are set correctly in vars.yml

matrix_domain: example.com
matrix_server_fqn_element: "<element-domain>"

• You cannot change this later without reinstallation.
• To secure communications, Matrix uses SSL certificates from Let’s Encrypt. Set your admin email in vars.yml to receive certificate renewal notifications:

traefik_config_certificatesResolvers_acme_email: '[email protected]'

• Matrix uses Traefik as a reverse proxy to manage SSL automatically.
• If using a custom web server, refer to the playbook documentation for manual SSL setup.
• Cloudflare users – Disable the proxy mode (use DNS only).
• Port 80/443 blocked – Ensure your firewall allows HTTP & HTTPS traffic.
• Matrix stores all user data, messages, and configurations in a database. Set a secure PostgreSQL password in vars.yml:

postgres_connection_password: '<strong-password>'

• The playbook automatically sets up the database for you.
• Use a strong, random password for PostgreSQL (e.g., pwgen -s 32 1).
• If your server has multiple IP addresses (e.g., private and public IPs), you must specify the correct one for services like TURN (for voice/video calls). Set the correct IP in vars.yml

matrix_coturn_turn_external_ip_address: 'your-public-ip'

## If your server has multiple IPs, define them as a list:
matrix_coturn_turn_external_ip_addresses: ['1.2.3.4', '5.6.7.8']

Common Issues with Multiple IPs

• Matrix calls not working? Check that the TURN server is using the correct external IP.

Create and Edit hosts File

The hosts file tells Ansible which server to install Matrix on.

Copy the sample hosts file:

cp examples/hosts inventory/hosts

Edit the file using a text editor:

nano inventory/hosts

Example configuration (hosts file)

[matrix_servers] matrix.example.com ansible_host=YOUR_SERVER_IP ansible_ssh_user=root

Replace YOUR_SERVER_IP with your actual server’s public IP address.
If using a non-root SSH user, change ansible_ssh_user=root to your user.

Now your configuration files are ready!

Issue: Playbook Fails Due to Old Role Versions

Cause: Some roles were not updated correctly.
Solution: Delete the roles directory and reinstall:

rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force

Why This Step is Critical

• Ensures your Matrix services are installed correctly
• Prevents errors during deployment due to outdated roles
• Keeps your Matrix server secure and up to date

Now that your Ansible roles are updated, the next step is running the installation command to deploy Matrix!

Running the Installation Command

Now that we have:
Updated and fetched all Ansible roles
Configured the Matrix playbook with the correct domain, SSL, database, and network settings

It’s time to run the installation command to deploy Matrix on your server! 🚀

In this section, we will cover:
Step-by-step execution of the installation process
Handling common issues and troubleshooting

Step-by-Step Execution of Matrix Installation

Step 1: Navigate to the Playbook Directory

Ensure you are inside the Matrix Ansible playbook folder before running the command:

cd matrix-docker-ansible-deploy

Step 2: Run the Installation Command

Execute the following Ansible command to install Matrix:

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

Explanation of the Command:

• ansible-playbook → Runs an Ansible automation script.
• -i inventory/hosts → Specifies the server inventory file.
• setup.yml → The main playbook file that installs Matrix services.
• --tags=install-all,ensure-matrix-users-created,start → Ensures all components are installed, users are created, and services are started.

Step 3: Enter SSH Credentials (If Required)

If you are not using SSH keys for authentication, Ansible may prompt for a password. If so, re-run the command with:

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

For Non-Root Users Using sudo
If your server does not allow direct root login, add the -K flag to enter your sudo password:

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

Step 4: Monitor the Installation Process

• The installation process will begin, and Ansible will start executing tasks such as:
• Installing required dependencies
• Configuring Matrix services (Synapse, PostgreSQL, Traefik, Coturn, Element Web, etc.)
• Generating SSL certificates
• Creating Matrix admin users

A successful installation should display a “PLAY RECAP” message at the end, confirming that everything was installed correctly.

If everything is green, your Matrix server is now installed and running!

Handling Common Issues & Troubleshooting

Issue 1: “Permission Denied” While Running the Playbook

Cause: The user does not have the required permissions to run Ansible.
Solution: Run the command as root or use sudo:

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

Issue 2: “ansible-playbook: command not found”

Cause: Ansible is not installed or is missing from the system path.
Solution: Install Ansible using:

sudo apt install ansible -y

After installation, retry the playbook command.

Issue 3: SSL Certificate Not Issued (Traefik Failure)

Cause: Let’s Encrypt could not issue a certificate.
Solution: Ensure ports 80 and 443 are open:

sudo ufw allow 80/tcp
sudo ufw allow 443/tcp

If using Cloudflare, disable the proxy (set DNS to “DNS Only”).

Restart Traefik and re-run the playbook:

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

Issue 4: Database Connection Issues (PostgreSQL Errors)

Cause: The Matrix server cannot connect to PostgreSQL.
Solution:

Check if PostgreSQL is running:

sudo systemctl status postgresql

Restart PostgreSQL if necessary:

sudo systemctl restart postgresql

Ensure your database password in vars.yml is correct:

postgres_connection_password: 'your-secure-db-password'

Issue 5: Federation Not Working (Other Servers Can’t Connect)

Cause: Matrix federation is blocked due to a firewall or incorrect DNS settings.
Solution: Ensure federation port (8448) is open:

sudo ufw allow 8448/tcp

Check DNS settings using nslookup or dig:

nslookup matrix.example.com

Ensure your server is accessible externally:

curl -v https://matrix.example.com:8448

How to Verify a Successful Installation?

After installation, check if your Matrix server is running:

Check Running Services

docker ps

If all containers (Synapse, Traefik, Coturn, PostgreSQL) are running, the setup was successful.

Access Element Web Client

Open a browser and go to:

https://element.example.com

You should see the Matrix login screen.

Test Matrix Federation

Use the Matrix Federation Tester:
https://federationtester.matrix.org/

Enter your domain (example.com) and check if federation is working.

Final Thoughts

• Running the installation command deploys all Matrix services automatically.
• Common issues like permission errors, SSL failures, or database issues can be fixed easily.
• If everything is set up correctly, you can log in and start using Matrix immediately! 🚀

Next Steps:
➡ Creating a User Account and Managing Your Matrix Server!

Creating a User Account in Matrix

After successfully installing your Matrix server, the next crucial step is creating a user account. This includes:

• Registering an admin account to manage your server
• Understanding user authentication
• Enhancing security measures to protect accounts

By following this guide, you will set up a secure, fully functional Matrix account and be ready to start messaging!

Registering an Admin Account

Matrix user accounts follow a format like:

@yourusername:example.com

Where:

• yourusername is your unique user ID.
• example.com is your Matrix domain.

To create a superuser (admin) account, follow these steps:

Run the User Registration Command

To register an admin user, run the following Ansible command from your playbook directory:

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=YOUR_USERNAME_HERE password=YOUR_PASSWORD_HERE admin=yes' --tags=register-user

Replace:

• YOUR_USERNAME_HERE → Your desired Matrix username (e.g., alice).
• YOUR_PASSWORD_HERE → A strong password.

Example Command:

ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=alice password=StrongPass123! admin=yes' --tags=register-user

This command creates an admin account with full control over the Matrix server.