From 325ddfe012314f1a78feb5bcfdd7263db8c13b58 Mon Sep 17 00:00:00 2001
From: Maddox <maddox@3ddbrewery.com>
Date: Sun, 1 Feb 2026 15:52:52 +0000
Subject: [PATCH] Initial commit: Matrix Ansible Controller

Portable Docker container for managing matrix-docker-ansible-deploy playbooks.

- Dockerfile with Python 3.12, Ansible 2.17+, and all dependencies
- docker-compose.yml with volume mounts for SSH, playbook, and inventory
- entrypoint.sh for automatic setup (clone playbook, link inventory, install roles)
- README.md with deployment and usage instructions
---
 .gitignore         |  13 +++
 Dockerfile         |  56 +++++++++++
 README.md          | 237 +++++++++++++++++++++++++++++++++++++++++++++
 docker-compose.yml |  49 ++++++++++
 entrypoint.sh      |  84 ++++++++++++++++
 5 files changed, 439 insertions(+)
 create mode 100644 .gitignore
 create mode 100644 Dockerfile
 create mode 100644 README.md
 create mode 100644 docker-compose.yml
 create mode 100755 entrypoint.sh

diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..1bdfd3a
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,13 @@
+# Data directory (contains cloned playbook, inventory with secrets, and cache)
+data/
+
+# Editor files
+*.swp
+*.swo
+*~
+.vscode/
+.idea/
+
+# OS files
+.DS_Store
+Thumbs.db
diff --git a/Dockerfile b/Dockerfile
new file mode 100644
index 0000000..3db94a7
--- /dev/null
+++ b/Dockerfile
@@ -0,0 +1,56 @@
+# Matrix Ansible Controller
+# Portable container for managing matrix-docker-ansible-deploy playbook
+
+FROM python:3.12-alpine
+
+LABEL maintainer="maddox"
+LABEL description="Portable Ansible controller for matrix-docker-ansible-deploy"
+
+# Install system dependencies
+RUN apk add --no-cache \
+    git \
+    openssh-client \
+    bash \
+    curl \
+    rsync \
+    gcc \
+    musl-dev \
+    libffi-dev \
+    openssl-dev \
+    python3-dev \
+    just \
+    nano \
+    vim \
+    tmux \
+    jq
+
+# Install Ansible and required Python packages
+RUN pip install --no-cache-dir \
+    ansible>=2.17.0 \
+    passlib \
+    dnspython \
+    netaddr \
+    jmespath \
+    docker \
+    requests
+
+# Create working directories
+RUN mkdir -p /playbook /inventory /ssh
+
+# Set up SSH directory with proper permissions
+RUN mkdir -p /root/.ssh && chmod 700 /root/.ssh
+
+# Copy entrypoint script
+COPY entrypoint.sh /entrypoint.sh
+RUN chmod +x /entrypoint.sh
+
+# Set working directory to playbook
+WORKDIR /playbook
+
+# Default environment
+ENV ANSIBLE_HOST_KEY_CHECKING=False
+ENV ANSIBLE_FORCE_COLOR=True
+ENV TERM=xterm-256color
+
+ENTRYPOINT ["/entrypoint.sh"]
+CMD ["/bin/bash"]
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..1c88865
--- /dev/null
+++ b/README.md
@@ -0,0 +1,237 @@
+# 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 ssh://git@git.3ddbrewery.com:2222/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/)
diff --git a/docker-compose.yml b/docker-compose.yml
new file mode 100644
index 0000000..66b7d7c
--- /dev/null
+++ b/docker-compose.yml
@@ -0,0 +1,49 @@
+# Matrix Ansible Controller
+# Portable container for managing matrix-docker-ansible-deploy playbook
+#
+# Usage:
+#   docker compose up -d
+#   docker exec -it matrix-ansible-controller bash
+#   just install-all
+
+services:
+  controller:
+    build: .
+    image: matrix-ansible-controller:latest
+    container_name: matrix-ansible-controller
+    hostname: matrix-controller
+    
+    # Keep container running for interactive use
+    stdin_open: true
+    tty: true
+    
+    volumes:
+      # SSH keys (read-only) - for connecting to matrix server
+      - /root/.ssh:/ssh:ro
+      
+      # Persistent playbook directory (survives container rebuilds)
+      - ./data/playbook:/playbook
+      
+      # Your inventory configuration (vars.yml, hosts, etc.)
+      - ./data/inventory:/inventory
+      
+      # Persist ansible cache/facts
+      - ./data/ansible-cache:/root/.ansible
+    
+    environment:
+      - ANSIBLE_HOST_KEY_CHECKING=False
+      - ANSIBLE_FORCE_COLOR=True
+      - UPDATE_ROLES=false
+    
+    network_mode: bridge
+    
+    deploy:
+      resources:
+        limits:
+          memory: 1G
+          cpus: '2.0'
+    
+    labels:
+      - "com.centurylinklabs.watchtower.enable=false"
+    
+    restart: unless-stopped
diff --git a/entrypoint.sh b/entrypoint.sh
new file mode 100755
index 0000000..cedc487
--- /dev/null
+++ b/entrypoint.sh
@@ -0,0 +1,84 @@
+#!/bin/bash
+set -e
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+echo -e "${BLUE}========================================${NC}"
+echo -e "${BLUE}  Matrix Ansible Controller${NC}"
+echo -e "${BLUE}========================================${NC}"
+
+# --- SSH Key Setup ---
+if [ -d "/ssh" ] && [ "$(ls -A /ssh 2>/dev/null)" ]; then
+    echo -e "${GREEN}[SSH]${NC} Setting up SSH keys from /ssh mount..."
+    cp -r /ssh/* /root/.ssh/ 2>/dev/null || true
+    chmod 700 /root/.ssh
+    chmod 600 /root/.ssh/* 2>/dev/null || true
+    chmod 644 /root/.ssh/*.pub 2>/dev/null || true
+    chmod 644 /root/.ssh/known_hosts 2>/dev/null || true
+    chmod 644 /root/.ssh/config 2>/dev/null || true
+    echo -e "${GREEN}[SSH]${NC} Keys configured"
+else
+    echo -e "${YELLOW}[SSH]${NC} No SSH keys mounted at /ssh"
+    echo -e "${YELLOW}[SSH]${NC} Mount with: -v ~/.ssh:/ssh:ro"
+fi
+
+# --- Playbook Setup ---
+if [ ! -f "/playbook/setup.yml" ]; then
+    echo -e "${GREEN}[PLAYBOOK]${NC} Cloning matrix-docker-ansible-deploy..."
+    git clone https://github.com/spantaleev/matrix-docker-ansible-deploy.git /tmp/playbook
+    mv /tmp/playbook/* /playbook/
+    mv /tmp/playbook/.* /playbook/ 2>/dev/null || true
+    rm -rf /tmp/playbook
+    echo -e "${GREEN}[PLAYBOOK]${NC} Playbook cloned successfully"
+else
+    echo -e "${GREEN}[PLAYBOOK]${NC} Playbook already present"
+fi
+
+# --- Inventory Setup ---
+if [ -d "/inventory" ] && [ "$(ls -A /inventory 2>/dev/null)" ]; then
+    echo -e "${GREEN}[INVENTORY]${NC} Linking inventory from /inventory mount..."
+    rm -rf /playbook/inventory 2>/dev/null || true
+    ln -sf /inventory /playbook/inventory
+    echo -e "${GREEN}[INVENTORY]${NC} Inventory linked: /playbook/inventory -> /inventory"
+else
+    echo -e "${YELLOW}[INVENTORY]${NC} No inventory mounted at /inventory"
+    echo -e "${YELLOW}[INVENTORY]${NC} Mount with: -v /path/to/inventory:/inventory"
+    mkdir -p /playbook/inventory
+fi
+
+# --- Install/Update Ansible Roles ---
+if [ -f "/playbook/requirements.yml" ]; then
+    if [ ! -d "/playbook/roles/galaxy" ] || [ "${UPDATE_ROLES:-false}" = "true" ]; then
+        echo -e "${GREEN}[ROLES]${NC} Installing Ansible Galaxy roles..."
+        cd /playbook
+        rm -rf roles/galaxy
+        ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force
+        echo -e "${GREEN}[ROLES]${NC} Roles installed successfully"
+    else
+        echo -e "${GREEN}[ROLES]${NC} Roles already installed (set UPDATE_ROLES=true to refresh)"
+    fi
+fi
+
+# --- Display Status ---
+echo ""
+echo -e "${BLUE}----------------------------------------${NC}"
+echo -e "${GREEN}Status:${NC}"
+echo -e "  Ansible:   $(ansible --version | head -1)"
+echo -e "  Playbook:  /playbook"
+echo -e "  Inventory: /playbook/inventory"
+echo ""
+echo -e "${BLUE}Quick Commands:${NC}"
+echo -e "  just install-all     # Full installation"
+echo -e "  just setup-all       # Setup all components"
+echo -e "  just roles           # Update roles"
+echo -e "  just update          # git pull + update roles"
+echo ""
+echo -e "${BLUE}----------------------------------------${NC}"
+echo ""
+
+exec "$@"