How to Deploy & Use spantaleev/matrix-docker-ansible-deploy

# Matrix Docker Ansible Deploy Guide

Complete deployment guide for running a Matrix homeserver using Ansible and Docker.

## 1. Prerequisites

### Control Node (Your Workstation)
- **Ansible** 2.9+ (2.12+ recommended)
- **Python** 3.6+
- **Git**
- **SSH** client with key-based authentication configured

### Target Server Requirements
- **OS**: Ubuntu 20.04/22.04, Debian 11/12, CentOS 7/8, or RHEL 8/9 (x86_64/ARM64)
- **Docker** 20.10+ and **Docker Compose** v2+
- **Ports**: 80/tcp (HTTP), 443/tcp (HTTPS), 8448/tcp (Matrix Federation)
- **Hardware**: 2GB RAM minimum (4GB+ recommended), 10GB disk (100GB+ recommended with media repository)
- **Privileges**: SSH access with passwordless sudo

### Domain & DNS
- Registered domain name (e.g., `example.com`)
- DNS A/AAAA records pointing to your server:
 - `matrix.example.com` (homeserver)
 - `element.example.com` (optional, for Element Web client)
- SRV record or `.well-known` delegation for federation (configured automatically)

## 2. Installation

```bash
# Clone the repository
git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git
cd matrix-docker-ansible-deploy

# Install Ansible collections and roles
ansible-galaxy install -r requirements.yml

# Create inventory directory structure
mkdir -p inventory/host_vars

3. Configuration

3.1 Inventory Setup (`inventory/hosts.yml`)

---
all:
  children:
    matrix_servers:
      hosts:
        matrix.example.com:  # Replace with your domain
          ansible_host: 203.0.113.1  # Replace with your server IP
          ansible_user: root  # Or your sudo user
          # ansible_ssh_private_key_file: ~/.ssh/id_rsa

3.2 Variables (`inventory/host_vars/matrix.example.com/vars.yml`)

---
# Required: Your Matrix domain (the part after @ in Matrix IDs)
matrix_domain: example.com

# Required: Admin email for SSL certificates
matrix_admin_email: admin@example.com

# Optional: Homeserver selection (Synapse is default)
# matrix_homeserver_implementation: synapse
# matrix_homeserver_implementation: conduit
# matrix_homeserver_implementation: dendrite

# Optional: Enable Element Web client
matrix_client_element_enabled: true

# Optional: Additional services (examples)
# matrix_bot_maubot_enabled: true
# matrix_synapse_admin_enabled: true

# SSL Certificate configuration (Let's Encrypt by default)
matrix_ssl_lets_encrypt_support_email: "{{ matrix_admin_email }}"

# Postgres configuration (auto-generated if omitted)
# matrix_postgres_connection_password: 'your-secure-password-here'

3.3 Secrets (Optional but Recommended)

Create inventory/host_vars/matrix.example.com/vault.yml for sensitive data:

---
vault_matrix_postgres_connection_password: 'super-secret-password'
vault_matrix_synapse_macaroon_secret_key: 'another-secret-key'

Encrypt with: ansible-vault encrypt inventory/host_vars/matrix.example.com/vault.yml

Reference in vars.yml:

matrix_postgres_connection_password: "{{ vault_matrix_postgres_connection_password }}"

4. Provision & Deploy

Initial Setup

Run the playbook to configure the server and start services:

# Full setup and start (recommended for first run)
ansible-playbook -i inventory/hosts.yml setup.yml --tags=setup-all,start

# Or using just (if installed)
just setup

This command will:

Install Docker and dependencies on the target server
Configure SSL certificates via Let's Encrypt
Start all containers (Synapse, Element, Postgres, etc.)
Configure reverse proxy (Traefik or nginx)

Create Admin User

After initial deployment, create an admin account:

# SSH into your server
ssh root@matrix.example.com

# Run the user creation script
/usr/local/bin/matrix-synapse-admin-register-user @admin:example.com <password>

Or for Conduit/Dendrite, use their respective admin creation commands.

Verify Deployment

Check service status:

# On the target server
docker ps
docker-compose -p matrix ps

Test federation:

curl https://matrix.example.com/_matrix/federation/v1/version

5. Deployment (Maintenance)

Updates

Regularly update to receive security patches and features:

# Pull latest playbook
git pull

# Update Ansible requirements
ansible-galaxy install -r requirements.yml --force

# Re-run setup (idempotent - safe to run multiple times)
ansible-playbook -i inventory/hosts.yml setup.yml --tags=setup-all

# Or restart services after update
ansible-playbook -i inventory/hosts.yml setup.yml --tags=setup-all,start

Adding/Removing Services

Edit vars.yml to enable new services, then re-run:

ansible-playbook -i inventory/hosts.yml setup.yml --tags=setup-all,start

Backup

The playbook does not auto-backup data. Configure backups for:

/matrix/synapse/config/ (configuration)
/matrix/postgres/data/ (database)
/matrix/synapse/storage/ (media files)

Example backup command:

# On target server
tar -czf matrix-backup-$(date +%F).tar.gz /matrix/synapse/config /matrix/postgres/data /matrix/synapse/storage

6. Troubleshooting

Ansible Connection Issues

Problem: UNREACHABLE! Failed to connect via SSH

Solution: Verify ansible_host IP and ansible_user in inventory/hosts.yml
Test with: ansible -i inventory/hosts.yml matrix_servers -m ping

Port Already in Use

Problem: Bind for 0.0.0.0:80 failed: port is already allocated

Solution: Stop existing web servers (Apache/nginx) or change matrix_nginx_proxy_port in vars.yml

SSL Certificate Failures

Problem: Let's Encrypt validation fails

Solution: Ensure DNS A record points to server IP and ports 80/443 are open to the internet
Check: curl -I http://matrix.example.com/.well-known/matrix/server

Database Connection Errors

Problem: Synapse fails to start with Postgres errors

Solution: Check Postgres container logs:
```
docker logs matrix-postgres
```

Federation Not Working

Problem: Cannot federate with other servers

Solution: Verify port 8448 is open and SRV record/.well-known is configured:

curl https://federationtester.matrix.org/api/report?server_name=example.com

Service Won't Start

Problem: Container keeps restarting

Solution: Check logs:

docker logs matrix-synapse
docker logs matrix-traefik  # or matrix-nginx-proxy

Resetting Everything

Warning: Destroys all data

# On target server
cd /matrix
docker-compose -p matrix down -v
rm -rf /matrix/*
# Then re-run playbook