Matrix is an open standard for decentralized communication, and Synapse is its reference implementation. If you want to set up your own Matrix server, using Docker and Ansible can make the process much smoother. This blog post will guide you through the setup process using the excellent matrix-docker-ansible-deploy repository by Slavi Pantaleev. Along the way, I’ll share some of my findings and the steps I took to overcome a few hurdles.

---

<h

,

sudo lsof -i :80

>Prerequisites</h

,

sudo lsof -i :80

>

Before diving into the setup, ensure your system meets the prerequisites outlined in the official documentation:

1. Clone the Repository:

   ,

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

   >

2. Install Required Dependencies:
   • First, ensure you have the necessary tools installed:

     ,

     sudo apt update
     sudo apt install curl git ansible
     

     >

   • Next, install Rust and just, a command runner that makes working with this setup easier:

     ,

     curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
     source $HOME/.cargo/env
     git clone https://github.com/casey/just.git
     cd just
     cargo build --release
     sudo mv target/release/just /usr/local/bin/
     just --version  # Verify the installation
     

     >

3. Firewall Configuration:
   Ensure your server is properly configured to allow necessary traffic:

   ,

   # Allow HTTP and HTTPS
   sudo ufw allow 80/tcp
   sudo ufw allow 443/tcp
   
   # Allow TURN ports
   sudo ufw allow 3478/tcp
   sudo ufw allow 3478/udp
   sudo ufw allow 5349/tcp
   sudo ufw allow 5349/udp
   
   # Allow Matrix Federation API
   sudo ufw allow 8448/tcp
   
   # Allow UDP port range for TURN
   sudo ufw allow 49152:49172/udp
   
   # Enable UFW if it's not already enabled
   sudo ufw enable
   
   # Verify the rules
   sudo ufw status verbose
   

   >

4. Check for Port Conflicts:
   Before proceeding, check if the necessary ports are already in use:

   ,

   sudo lsof -i :80
   

   >

   If port

   ,

   just register-user <your-username> <your-password> <admin access: yes or no>
   

   ,

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

   is occupied, resolve the conflict before continuing.

---

<h

,

sudo lsof -i :80

>Setting Up the Matrix Server</h

,

sudo lsof -i :80

>

With the prerequisites in place, you can proceed with the server setup.

1. Install Ansible Galaxy Dependencies:
   From within the matrix-docker-ansible-deploy directory:

   ,

   ansible-galaxy install -r requirements.yml
   

   >

2. Run the Setup Playbook:
   Use just to install all necessary roles and start the server:

   ,

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

   >

3. Dealing with Service Failures:
   During my setup, I encountered an issue with the matrix-traefik service failing to start due to a port conflict:

   ,

   systemd[1]: matrix-traefik.service: Main process exited, code=exited, status=1/FAILURE
   systemd[1]: matrix-traefik.service: Failed with result 'exit-code'.
   systemd[1]: matrix-traefik.service: Scheduled restart job, restart counter is at 289.
   

   >

   The solution was to identify which service was occupying port

   ,

   just register-user <your-username> <your-password> <admin access: yes or no>
   

   ,

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

   and either stop it or configure traefik to use a different port.

4. Configuring Matrix Synapse:
   • If you need to register users, you can use the just command:

     ,

     just register-user <your-username> <your-password> <admin access: yes or no>
     

     >

   • To configure Synapse further, such as disabling the ability to join remote rooms:

     ,

     sudo su - matrix
     nano /matrix/synapse/config/homeserver.yaml
     

     >

     Add or modify the following configuration:

     ,

     sudo apt update
     sudo apt install curl git ansible
     

     ,

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

     >

   • After making changes, restart the Synapse service:

     ,

     sudo apt update
     sudo apt install curl git ansible
     

     ,

     sudo apt update
     sudo apt install curl git ansible
     

     >

---

<h

,

sudo lsof -i :80

>Final Thoughts and Support</h

,

sudo lsof -i :80

>

Setting up a Matrix server using Docker and Ansible with matrix-docker-ansible-deploy is a powerful and flexible approach, especially if you plan to manage multiple services or scale your deployment. However, it’s important to be prepared for some potential troubleshooting along the way, especially when it comes to port conflicts and service configurations.

The Matrix community and the maintainers of this playbook offer fantastic support:

• Matrix Room: #matrix-docker-ansible-deploy:devture.com
• IRC Channel: #matrix-docker-ansible-deploy on the Libera Chat IRC network (irc.libera.chat:

  ,

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

  ,

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

  ,

  sudo su - matrix
  nano /matrix/synapse/config/homeserver.yaml
  

  ,

  systemd[1]: matrix-traefik.service: Main process exited, code=exited, status=1/FAILURE
  systemd[1]: matrix-traefik.service: Failed with result 'exit-code'.
  systemd[1]: matrix-traefik.service: Scheduled restart job, restart counter is at 289.
  

   

  )

• GitHub Issues: spantaleev/matrix-docker-ansible-deploy/issues