maddox/matrix-ansible-controller
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Initial commit: Matrix Ansible Controller

Browse source 
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
This commit is contained in:
Maddox 2026-02-01 15:52:52 +00:00
commit 325ddfe012
5 changed files with 439 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

13
.gitignore vendored Normal file
View file

@ -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

56
Dockerfile Normal file
View file

@ -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"]

237
README.md Normal file
View file

@ -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/)

49
docker-compose.yml Normal file
View file

@ -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

84
entrypoint.sh Executable file
View file

@ -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 "$@"