Skip to content

Solti Matrix Manager Collection

Ansible collection for managing Matrix Synapse homeservers and posting structured events to Matrix rooms.

Overview

The jackaltx.solti_matrix_mgr collection provides modules and roles for:

  • User Management - Create, update, and deactivate Matrix users (including bot accounts)
  • Room Management - Create, query, and delete Matrix rooms
  • Device/Token Management - Audit and cleanup access tokens
  • Event Notifications - Post structured events to Matrix rooms
  • Configuration Management - Deploy Synapse config overlays and appservices

Quick Start

Prerequisites

1. Credentials File

Create ~/.secrets/LabMatrix with your Matrix homeserver credentials:

# Matrix Homeserver Configuration
export MATRIX_HOMESERVER_URL="https://matrix.example.com"

# Admin Account (for user/room management)
export MATRIX_ADMIN_USER="@admin:example.com"
export MATRIX_ADMIN_PASSWORD="your-admin-password"
export MATRIX_ADMIN_TOKEN=""  # Auto-populated by get-admin-token.sh

# Bot Account (for event notifications)
export MATRIX_BOT_USER="@bot:example.com"
export MATRIX_BOT_PASSWORD="your-bot-password"
export MATRIX_BOT_TOKEN=""  # Auto-populated by login scripts

# Default Room (optional)
export MATRIX_DEFAULT_ROOM="#notifications:example.com"

Security: 

chmod 600 ~/.secrets/LabMatrix

Usage in playbooks: 

source ~/.secrets/LabMatrix
ansible-playbook matrix-tasks.yml

2. Installation

# Install from Ansible Galaxy
ansible-galaxy collection install jackaltx.solti_matrix_mgr

# Verify installation
ansible-galaxy collection list | grep solti_matrix_mgr

Basic Usage

---
- name: Matrix Administration Example
  hosts: localhost
  gather_facts: false

  tasks:
    - name: Create bot user
      jackaltx.solti_matrix_mgr.synapse_user:
        homeserver_url: "https://matrix.example.com"
        admin_user: "@admin:example.com"
        admin_password: "{{ admin_password }}"
        user_id: "@bot:example.com"
        password: "{{ bot_password }}"
        displayname: "Notification Bot"
        user_type: bot
        state: present

    - name: Post event to room
      jackaltx.solti_matrix_mgr.matrix_event:
        homeserver_url: "https://matrix.example.com"
        access_token: "{{ bot_token }}"
        room_id: "#notifications:example.com"
        content:
          msgtype: "m.text"
          body: "Deployment completed successfully"

Key Features

Self-Healing Authentication

Modules automatically refresh expired tokens using admin credentials: 

# Token expired? No problem - provide credentials
synapse_user:
  homeserver_url: "{{ url }}"
  access_token: "{{ expired_token }}"
  admin_user: "{{ admin_user }}"
  admin_password: "{{ admin_password }}"
  # ... module will auto-refresh token

User Type Support

Classify users with user_type for MAU exemption and filtering: 

# Bot users don't count toward MAU limits
synapse_user:
  user_id: "@logger:example.com"
  user_type: bot
  state: present

# Query all bot users
synapse_user_info:
  user_type: bot

Idempotent Operations

All modules support check mode and are fully idempotent: 

# Test changes without applying
ansible-playbook playbook.yml --check

# Apply only necessary changes
ansible-playbook playbook.yml

Architecture

Token Management Pattern

┌─────────────────────────────────────────┐
│ ~/.secrets/LabMatrix                    │  ← Single source of truth
├─────────────────────────────────────────┤
│ MATRIX_ADMIN_USER                       │
│ MATRIX_ADMIN_PASSWORD                   │
│ MATRIX_ADMIN_TOKEN (cached)             │  ← Auto-updated
└─────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│ Ansible Playbooks                       │
├─────────────────────────────────────────┤
│ source ~/.secrets/LabMatrix             │
│ ansible-playbook matrix-tasks.yml       │
└─────────────────────────────────────────┘
                 │
                 ▼
┌─────────────────────────────────────────┐
│ Matrix Synapse Server                   │
├─────────────────────────────────────────┤
│ Admin API (/_synapse/admin/...)         │
│ Client API (/_matrix/client/...)        │
└─────────────────────────────────────────┘

Module Reference

Admin API Modules

Client API Modules

Documentation

Deployment Patterns

Pattern 1: Proxmox LXC Container

LXC Container
├── /etc/synapse/
│   ├── homeserver.yaml
│   ├── conf.d/              ← Ansible overlays
│   └── appservices/         ← Bridge registrations
└── Synapse (systemd)
    └── Admin API :8008

Pattern 2: Docker Compose

Docker Compose Stack
├── /matrix/synapse/config/  ← Ansible overlays
├── /matrix/hookshot/        ← Webhook configs
└── Containers
    ├── synapse
    ├── postgres
    └── hookshot

Testing

Comprehensive Molecule testing with: - default - Event posting and self-healing auth - user-mgmt - User creation with user_type support - e2e - Full integration with Docker Synapse (GitHub Actions)

# Run user management tests
molecule test -s user-mgmt

# Run e2e tests (requires Docker)
molecule test -s e2e

License

MIT-0 - Free to use without restriction.