matrix-ansible-controller/README.md

Matrix Ansible Controller

A portable Docker container for managing matrix-docker-ansible-deploy playbooks. This container provides a consistent Ansible environment with all required dependencies pre-installed.

Features

• Python 3.12 with Ansible 2.17+
• All required Python packages (passlib, dnspython, netaddr, jmespath, docker)
• just command runner for simplified playbook execution
• Automatic playbook cloning and role installation
• Persistent storage for playbook, inventory, and Ansible cache

Prerequisites

• Docker and Docker Compose
• SSH key pair that can authenticate to your Matrix server as root
• Your Matrix server inventory configuration (hosts file and vars.yml)

Quick Start

1. Clone this repository

git clone https://git.3ddbrewery.com/maddox/matrix-ansible-controller.git
cd matrix-ansible-controller

2. Create the data directory structure

mkdir -p data/inventory/host_vars/matrix.YOUR-DOMAIN.com
mkdir -p data/playbook
mkdir -p data/ansible-cache

3. Create your inventory files

Create data/inventory/hosts:

# Matrix server inventory
# Replace YOUR-DOMAIN.com and YOUR-SERVER-IP with your values

[matrix_servers]
matrix.YOUR-DOMAIN.com ansible_host=YOUR-SERVER-IP ansible_ssh_user=root

Create data/inventory/host_vars/matrix.YOUR-DOMAIN.com/vars.yml:

See the matrix-docker-ansible-deploy documentation for full configuration options. A minimal example:

---
# Base domain (user IDs will be @user:YOUR-DOMAIN.com)
matrix_domain: YOUR-DOMAIN.com

# Homeserver implementation
matrix_homeserver_implementation: synapse

# Secret key - generate with: pwgen -s 64 1
matrix_homeserver_generic_secret_key: YOUR-SECRET-KEY-HERE

# Reverse proxy (use Traefik managed by the playbook)
matrix_playbook_reverse_proxy_type: playbook-managed-traefik

# Postgres password - generate with: pwgen -s 64 1
devture_postgres_connection_password: YOUR-POSTGRES-PASSWORD-HERE

# Enable IPv6 in container networks
devture_systemd_docker_base_ipv6_enabled: true

4. Set up SSH keys

Ensure the host running Docker has SSH keys that can connect to your Matrix server:

# The container mounts /root/.ssh from the host
# Verify keys exist on the Docker host:
sudo ls -la /root/.ssh/id_*

# If no keys exist, generate or copy your keys:
sudo cp ~/.ssh/id_ed25519 /root/.ssh/
sudo cp ~/.ssh/id_ed25519.pub /root/.ssh/
sudo chmod 600 /root/.ssh/id_ed25519

# Test SSH to your Matrix server:
sudo ssh root@YOUR-SERVER-IP

5. Start the container

docker compose up -d

6. Enter the container and verify

docker exec -it matrix-ansible-controller bash

# Inside container - verify setup:
ansible -i inventory/hosts all -m ping
just --list

Usage

Common Commands

All commands are run inside the container:

docker exec -it matrix-ansible-controller bash

Command	Description
just update	Git pull playbook + update Ansible roles
just roles	Install/update Ansible Galaxy roles only
just install-all	Full installation (setup + start all services)
just setup-all	Configure all services without starting
just start-all	Start all services
just stop-all	Stop all services
just run-tags <tags>	Run specific tags (e.g., just run-tags setup-synapse)

First-Time Installation

# Enter container
docker exec -it matrix-ansible-controller bash

# Update playbook and roles
just update

# Verify connectivity
ansible -i inventory/hosts all -m ping

# Run full installation
just install-all

Updating Your Matrix Server

docker exec -it matrix-ansible-controller bash
just update
just install-all

Registering Users

# Register a regular user
just register-user USERNAME PASSWORD no

# Register an admin user
just register-user USERNAME PASSWORD yes

Troubleshooting

Git "dubious ownership" error

If you see this error when running just update:

fatal: detected dubious ownership in repository at /playbook

Fix it with:

git config --global --add safe.directory /playbook

SSH connection issues

1. Verify SSH keys are mounted:

   ls -la /root/.ssh/
   

2. Test SSH manually:

   ssh -v root@YOUR-SERVER-IP
   

3. Check known_hosts:

   ssh-keyscan YOUR-SERVER-IP >> /root/.ssh/known_hosts
   

Ansible connectivity test

ansible -i inventory/hosts all -m ping -vvv

View playbook help

just

Directory Structure

matrix-ansible-controller/
├── Dockerfile              # Container image definition
├── docker-compose.yml      # Docker Compose configuration
├── entrypoint.sh           # Container startup script
├── README.md               # This file
└── data/                   # Persistent data (git-ignored)
    ├── playbook/           # Cloned matrix-docker-ansible-deploy repo
    ├── inventory/          # Your Matrix configuration
    │   ├── hosts           # Ansible inventory file
    │   └── host_vars/
    │       └── matrix.YOUR-DOMAIN.com/
    │           └── vars.yml
    └── ansible-cache/      # Ansible fact cache

Volume Mounts

Container Path	Host Path	Purpose
/ssh	/root/.ssh	SSH keys (read-only)
/playbook	./data/playbook	Cloned playbook repo
/inventory	./data/inventory	Your inventory config
/root/.ansible	./data/ansible-cache	Ansible cache

References

• matrix-docker-ansible-deploy
• Configuring the Playbook
• Ansible Documentation