Skip to content

Introduction to Solti Matrix Manager

The jackaltx.solti_matrix_mgr Ansible collection provides comprehensive tooling for managing Matrix Synapse homeservers and integrating Matrix as a notification platform for infrastructure automation.

What is Matrix?

Matrix is an open standard for decentralized, real-time communication. Think of it as an open-source alternative to Slack or Discord, but federated like email.

Matrix Synapse is the reference homeserver implementation, providing: - User and room management - End-to-end encryption - Federation with other Matrix servers - RESTful Admin and Client APIs - Extensive configuration options

Why Use Matrix for Infrastructure?

Centralized Notifications

Post deployment results, verification reports, and system events to Matrix rooms where your team already communicates.

Structured Events

Send rich, structured data as Matrix events: 

{
  "msgtype": "com.solti.deployment",
  "body": "Deployment completed",
  "solti": {
    "schema": "deployment.v1",
    "environment": "production",
    "status": "success",
    "duration_seconds": 142
  }
}

Audit Trail

All events are permanently logged in Matrix rooms, providing an immutable audit trail of infrastructure changes.

Team Collaboration

Notifications appear alongside team discussion, enabling quick response to issues.

Collection Capabilities

User Management

  • Create and deactivate users programmatically
  • Support for bot accounts with MAU exemption
  • Bulk user provisioning from inventory
  • User type classification (bot, support, normal)

Room Management

  • Create rooms with custom power levels
  • Query rooms by ID or alias
  • Programmatic room deletion
  • Room membership management

Token Management

  • Self-healing authentication (auto-refresh expired tokens)
  • Device/token auditing and cleanup
  • Single source of truth pattern (~/.secrets/LabMatrix)
  • Scheduled token rotation

Event Notifications

  • Post arbitrary content to Matrix rooms
  • Support for custom message types
  • Structured event schemas
  • Integration with Ansible playbook results

Configuration Management

  • Deploy Synapse config overlays
  • Manage appservice registrations
  • Configure webhooks (matrix-hookshot)

Use Cases

Deployment Notifications

- name: Notify Matrix of deployment
  jackaltx.solti_matrix_mgr.matrix_event:
    homeserver_url: "{{ matrix_url }}"
    access_token: "{{ bot_token }}"
    room_id: "#deploys:example.com"
    content:
      msgtype: "m.text"
      body: "Deployed {{ app_name }} v{{ version }} to {{ environment }}"

Verification Results

- name: Post test results to Matrix
  jackaltx.solti_matrix_mgr.matrix_event:
    room_id: "#ci:example.com"
    content:
      msgtype: "com.solti.verification"
      body: "Test suite passed: {{ passed }}/{{ total }}"
      solti:
        schema: "verification.v1"
        status: "{{ 'pass' if passed == total else 'fail' }}"
        test_results: "{{ test_data }}"

Bot Account Provisioning

- name: Create monitoring bot
  jackaltx.solti_matrix_mgr.synapse_user:
    homeserver_url: "{{ matrix_url }}"
    admin_user: "@admin:example.com"
    admin_password: "{{ admin_password }}"
    user_id: "@monitor-bot:example.com"
    password: "{{ bot_password }}"
    displayname: "System Monitor"
    user_type: bot  # Exempt from MAU limits
    state: present

Token Cleanup

- name: Audit stale tokens
  jackaltx.solti_matrix_mgr.synapse_device_info:
    homeserver_url: "{{ matrix_url }}"
    access_token: "{{ admin_token }}"
    user_id: "@admin:example.com"
  register: devices

- name: Report stale devices
  debug:
    msg: "Found {{ devices.total }} devices, {{ stale_count }} are stale"

Key Design Principles

Idempotency First

All modules support check mode and are fully idempotent. Running the same playbook twice produces the same result.

Self-Healing Authentication

Modules automatically refresh expired tokens when admin credentials are provided, eliminating manual token management.

Single Source of Truth

Token management follows a consistent pattern: - Credentials in ~/.secrets/LabMatrix - Scripts update cached tokens - Playbooks source credentials from one location

Testing at Scale

Comprehensive Molecule testing across multiple scenarios: - Local testing with live Matrix server - Docker-based E2E testing in CI/CD - User management and lifecycle testing

Next Steps