matrix-docker-ansible-installation
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:
Because of these benefits, Matrix is widely used by developers, businesses, activists, and privacy-conscious users who want more control over their communication platforms.
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:
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.
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.
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 -yThis command:
For Mac users, Ansible can be installed using Homebrew:
brew install ansibleOnce 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 --versionThe 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.
Ansible relies on Python, so you need to install it along with Passlib, a library required for password hashing.
Use the following command to install Python and Pip (Python’s package manager):
sudo apt install python3 python3-pip -yOnce Python is installed, you need to install Passlib, which is required for managing authentication securely:
pip install passlibTip: If you face permission errors, try adding --user at the end of the command:
pip install --user passlibGit is required to download the Matrix Ansible playbook from its official repository.
To install Git, run:
sudo apt install git -yAfter installation, verify that Git is installed correctly:
git --versionThis will display the installed Git version, confirming that the setup is complete.
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.
For optimal performance, your server should have:
Tip: A dedicated VPS or cloud server (like AWS, DigitalOcean, or Linode) is ideal for hosting Matrix.
Matrix works best on Linux-based servers. The following OS versions are officially supported:
Note:
sudo apt install docker.io docker-compose -yTo allow Matrix services to function properly, certain ports must be open in your firewall.
Here’s a list of required ports:
| Port | Protocol | Purpose |
|---|---|---|
| 80 | TCP | HTTP (used for Let’s Encrypt SSL certificates) |
| 443 | TCP & UDP | HTTPS (secure web communication) |
| 3478 | TCP & UDP | TURN (for voice/video calls) |
| 5349 | TCP & UDP | TURN (alternative port for media relay) |
| 8448 | TCP & UDP | Matrix Federation API (communication between servers) |
| 49152-49172 | UDP | TURN over UDP (required for WebRTC calls) |
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 enableTip: 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.
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:
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:
| Type | Host | Priority | Weight | Port | Target |
|---|---|---|---|---|---|
| A | matrix | – | – | – | Server IP Address |
| CNAME | element | – | – | – | matrix.example.com |
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:
matrix.Why This Is Important?
This configuration ensures that users can register, log in, and send messages using your self-hosted Matrix server.
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:
element.matrix.example.com.Why This Is Important?
If you are using Cloudflare as your DNS provider, there are a few important settings to check:
Disable Cloudflare Proxy for Matrix Records
How to Disable Cloudflare Proxy?
matrix.example.com and element.example.com).Why This Is Important?
Note:
chat.example.com instead of matrix.example.com). Just make sure your DNS records match your Matrix playbook configuration.Now that your DNS is configured, we can move on to the next step: 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?
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.
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.gitWhat Happens Here?
matrix-docker-ansible-deploy.Once the repository is cloned, move into the directory where the playbook files are stored:
cd matrix-docker-ansible-deployThis is where all configurations and installation steps will be performed.
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 mainWhy Is This Important?
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.
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.
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.)vars.ymlThe 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.ymlOpen it in a text editor (like nano) for editing:
nano inventory/host_vars/matrix.example.com/vars.ymlHere’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: someone@example.com
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:
pwgen -s 64 1) for security.## Example Matrix ID
User: @alice:example.com
Server: matrix.example.commatrix_domain“ and “matrix_server_fqn_element” are set correctly in vars.ymlmatrix_domain: example.com
matrix_server_fqn_element: "<element-domain>"vars.yml to receive certificate renewal notifications:traefik_config_certificatesResolvers_acme_email: 'admin@example.com'vars.yml:postgres_connection_password: '<strong-password>'pwgen -s 32 1).vars.ymlmatrix_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
hosts FileThe hosts file tells Ansible which server to install Matrix on.
Copy the sample hosts file:
cp examples/hosts inventory/hostsEdit the file using a text editor:
nano inventory/hostsExample configuration (hosts file)
[matrix_servers] matrix.example.com ansible_host=YOUR_SERVER_IP ansible_ssh_user=rootReplace 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!
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/ --forceWhy This Step is Critical
Now that your Ansible roles are updated, the next step is running the installation command to deploy Matrix!
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
Ensure you are inside the Matrix Ansible playbook folder before running the command:
cd matrix-docker-ansible-deployExecute the following Ansible command to install Matrix:
ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,startExplanation 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.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-passFor 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 -KA 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!
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,startCause: Ansible is not installed or is missing from the system path.
Solution: Install Ansible using:
sudo apt install ansible -yAfter installation, retry the playbook command.
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/tcpIf 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,startCause: The Matrix server cannot connect to PostgreSQL.
Solution:
Check if PostgreSQL is running:
sudo systemctl status postgresqlRestart PostgreSQL if necessary:
sudo systemctl restart postgresqlEnsure your database password in vars.yml is correct:
postgres_connection_password: 'your-secure-db-password'Cause: Matrix federation is blocked due to a firewall or incorrect DNS settings.
Solution: Ensure federation port (8448) is open:
sudo ufw allow 8448/tcpCheck DNS settings using nslookup or dig:
nslookup matrix.example.comEnsure your server is accessible externally:
curl -v https://matrix.example.com:8448After installation, check if your Matrix server is running:
docker psIf all containers (Synapse, Traefik, Coturn, PostgreSQL) are running, the setup was successful.
Open a browser and go to:
https://element.example.comYou should see the Matrix login screen.
Use the Matrix Federation Tester:
https://federationtester.matrix.org/
Enter your domain (example.com) and check if federation is working.
Next Steps:
➡ Creating a User Account and Managing Your Matrix Server!
After successfully installing your Matrix server, the next crucial step is creating a user account. This includes:
By following this guide, you will set up a secure, fully functional Matrix account and be ready to start messaging!
Matrix user accounts follow a format like:
@yourusername:example.comWhere:
yourusername is your unique user ID.example.com is your Matrix domain.To create a superuser (admin) account, follow these steps:
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-userReplace:
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-userThis command creates an admin account with full control over the Matrix server.
What is Rallly? Rallly is an open-source scheduling and collaboration tool designed to make it…
Introduction OpenProject is a project management tool designed to help teams organize, collaborate, and track…
Hey there! Welcome back to the website, and today we're diving deeper into Jitsi Meet.…
Introduction Boost your team's collaboration and productivity with Mattermost, a secure and versatile communication platform.…
Introduction n8n.io is your secret weapon for workflow automation! It's a user-friendly platform that lets…
What is Nextcloud? Nextcloud is an awesome open-source platform that gives you exactly that. Think…