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
This commit is contained in:
Maddox
commit
325ddfe012
5 changed files with 439 additions and 0 deletions
13
.gitignore
vendored
Normal file
13
.gitignore
vendored
Normal 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
56
Dockerfile
Normal 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
237
README.md
Normal 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
49
docker-compose.yml
Normal 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
84
entrypoint.sh
Executable 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 "$@"
|
||||
Loading…
Reference in a new issue