matrix-ansible-controller/README.md

# Matrix Ansible Controller

A portable Docker container for managing [matrix-docker-ansible-deploy](https://github.com/spantaleev/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

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

### 2. Create the data directory structure

```bash
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`:**

```ini
# 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](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md) for full configuration options. A minimal example:

```yaml
---
# 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:

```bash
# 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

```bash
docker compose up -d
```

### 6. Enter the container and verify

```bash
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:

```bash
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

```bash
# 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

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

### Registering Users

```bash
# 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:

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

### SSH connection issues

1. Verify SSH keys are mounted:
   ```bash
   ls -la /root/.ssh/
   ```

2. Test SSH manually:
   ```bash
   ssh -v root@YOUR-SERVER-IP
   ```

3. Check known_hosts:
   ```bash
   ssh-keyscan YOUR-SERVER-IP >> /root/.ssh/known_hosts
   ```

### Ansible connectivity test

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

### View playbook help

```bash
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](https://github.com/spantaleev/matrix-docker-ansible-deploy)
- [Configuring the Playbook](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook.md)
- [Ansible Documentation](https://docs.ansible.com/)