homelab/compose/services/matrix/INTEGRATIONS-SETUP.md

Matrix Integrations Setup Guide

This guide covers setup for all Matrix integrations in your homelab.

Quick Start

1. Start all services:

   cd /home/eduardo_figueroa/homelab/compose/services/matrix
   docker compose up -d
   

2. Check service health:

   docker compose ps
   docker compose logs -f
   

---

Services Overview

Service	URL	Purpose
Synapse	https://matrix.fig.systems	Matrix homeserver
Element	https://chat.fig.systems	Web client
Synapse Admin	https://admin.matrix.fig.systems	User/room management
Maubot	https://maubot.fig.systems	Bot management
Matrix Registration	https://reg.matrix.fig.systems	Token-based registration
Hookshot	https://hookshot.fig.systems	GitHub/GitLab webhooks

---

1. Synapse Admin

Purpose: Web UI for managing users, rooms, and server settings.

Setup:

1. Access the UI:

   • Navigate to https://admin.matrix.fig.systems
   • Enter homeserver URL: https://matrix.fig.systems

2. Login with your admin account:

   • Use your Matrix credentials (@username:fig.systems)
   • Must be a server admin (see below to grant admin)

3. Grant admin privileges to a user:

   docker compose exec synapse register_new_matrix_user \
     -u <username> \
     -p <password> \
     -a \
     -c /data/homeserver.yaml \
     http://localhost:8008
   

Features:

• View and manage all users
• Deactivate accounts
• Manage rooms (delete, view members)
• View server statistics
• Media management

---

2. Matrix Registration (Token-Based Registration)

Purpose: Control who can register with invite tokens.

Admin Access:

Admin credentials:

• URL: https://reg.matrix.fig.systems/admin
• Secret: 4a385519f20e015faf06996f12532236aa02d15511ea48bf1abec32e21d40188 (Also in .env as MATRIX_REGISTRATION_ADMIN_SECRET)

Creating Registration Tokens:

Via Web UI:

1. Go to https://reg.matrix.fig.systems/admin
2. Enter the admin secret above
3. Click "Create Token"
4. Configure options:
   • One-time use: Token works only once
   • Multi-use: Token can be used multiple times
   • Expiration date: Token expires after this date
   • Disable email: Skip email verification for this token
5. Copy the token and share with users

Registration URL format:

https://reg.matrix.fig.systems?token=<your_token_here>

Creating Tokens via API:

# Create a one-time token
curl -X POST https://reg.matrix.fig.systems/api/token \
  -H "Authorization: Bearer 4a385519f20e015faf06996f12532236aa02d15511ea48bf1abec32e21d40188" \
  -H "Content-Type: application/json" \
  -d '{
    "ex_date": "2026-12-31",
    "one_time": true,
    "disable_email": false
  }'

# Create a multi-use token (for family/friends)
curl -X POST https://reg.matrix.fig.systems/api/token \
  -H "Authorization: Bearer 4a385519f20e015faf06996f12532236aa02d15511ea48bf1abec32e21d40188" \
  -H "Content-Type: application/json" \
  -d '{
    "ex_date": "2026-12-31",
    "one_time": false,
    "max_usage": 10,
    "disable_email": true
  }'

# List all tokens
curl https://reg.matrix.fig.systems/api/tokens \
  -H "Authorization: Bearer 4a385519f20e015faf06996f12532236aa02d15511ea48bf1abec32e21d40188"

# Disable a token
curl -X PUT https://reg.matrix.fig.systems/api/token/<token_name> \
  -H "Authorization: Bearer 4a385519f20e015faf06996f12532236aa02d15511ea48bf1abec32e21d40188" \
  -H "Content-Type: application/json" \
  -d '{"disabled": true}'

User Registration Process:

1. Admin creates token via web UI or API
2. Admin shares URL: https://reg.matrix.fig.systems?token=abc123
3. User opens URL and fills in:
   • Username
   • Password
   • Email (if required)
4. Account is created on your Matrix server

Benefits:

• Control who can register
• Track which tokens were used
• Bypass email verification per-token
• Prevent spam/abuse
• Invite-only registration system

---

3. Maubot (Bot Framework)

Purpose: Modular bot system for GIFs, reminders, RSS, and custom commands.

Initial Setup:

1. Generate initial config:

   docker compose run --rm maubot
   

2. Access the management UI:

   • URL: https://maubot.fig.systems
   • Default credentials are in /mnt/media/matrix/maubot/config.yaml

3. Login and change password:

   • First login with default credentials
   • Go to Settings → Change password

Creating a Bot User:

1. Register a bot user on your homeserver:

   docker compose exec synapse register_new_matrix_user \
     -u bot \
     -p <bot_password> \
     -c /data/homeserver.yaml \
     http://localhost:8008
   

2. Add bot client in Maubot UI:

   • Go to https://maubot.fig.systems
   • Click "Clients" → "+"
   • Enter:
     • User ID: @bot:fig.systems
     • Access Token: (get from login)
     • Homeserver: https://matrix.fig.systems

3. Get access token:

   curl -X POST https://matrix.fig.systems/_matrix/client/r0/login \
     -H "Content-Type: application/json" \
     -d '{
       "type": "m.login.password",
       "user": "bot",
       "password": "<bot_password>"
     }'
   

   Copy the access_token from the response.

Installing Plugins:

Popular plugins:

1. Giphy - /giphy <search> command

   • Download: https://github.com/TomCasavant/GiphyMaubot
   • Upload .mbp file in Maubot UI

2. Tenor - /tenor <search> GIF search

   • Download: https://github.com/williamkray/maubot-tenor

3. Reminder - /remind <time> <message>

   • Download: https://github.com/maubot/reminder

4. RSS - RSS feed notifications

   • Download: https://github.com/maubot/rss

5. Reactions - Emoji reactions and karma

   • Download: https://github.com/maubot/reactbot

6. Media - Download media from URLs

   • Download: https://github.com/maubot/media

Installation steps:

1. Download plugin .mbp file
2. Go to Maubot UI → Plugins → Upload
3. Create instance: Instances → + → Select plugin and client
4. Configure and enable

---

4. Telegram Bridge (mautrix-telegram)

Purpose: Bridge Telegram chats and DMs to Matrix.

Setup:

1. Get Telegram API credentials:

   • Go to https://my.telegram.org/apps
   • Log in with your phone number
   • Create an app
   • Copy api_id and api_hash

2. Generate config:

   docker compose run --rm mautrix-telegram
   

3. Edit config:

   nano /mnt/media/matrix/bridges/telegram/config.yaml
   

   Key settings:

   homeserver:
       address: http://synapse:8008
       domain: fig.systems
   
   appservice:
       address: http://mautrix-telegram:29317
       hostname: 0.0.0.0
       port: 29317
       database: sqlite:///data/mautrix-telegram.db
   
   bridge:
       permissions:
           '@yourusername:fig.systems': admin
           'fig.systems': user
   
   telegram:
       api_id: YOUR_API_ID
       api_hash: YOUR_API_HASH
   

4. Start the bridge:

   docker compose up -d mautrix-telegram
   

5. Restart Synapse (to load the registration file):

   docker compose restart synapse
   

Using the Bridge:

1. Start chat with bridge bot:

   • In Element, start a DM with @telegrambot:fig.systems
   • Send: login
   • Enter your Telegram phone number
   • Enter the code sent to Telegram

2. Bridge a chat:

   • Create or open a Matrix room
   • Invite @telegrambot:fig.systems
   • Send: !tg bridge <telegram_chat_id>
   • Or use !tg search <query> to find chats

3. Useful commands:

   • !tg help - Show all commands
   • !tg pm - Bridge personal chats
   • !tg search <query> - Find Telegram chats
   • !tg sync - Sync members/messages
   • !tg unbridge - Remove bridge

---

5. WhatsApp Bridge (mautrix-whatsapp)

Purpose: Bridge WhatsApp chats to Matrix.

Setup:

1. Generate config:

   docker compose run --rm mautrix-whatsapp
   

2. Edit config:

   nano /mnt/media/matrix/bridges/whatsapp/config.yaml
   

   Update:

   homeserver:
       address: http://synapse:8008
       domain: fig.systems
   
   bridge:
       permissions:
           '@yourusername:fig.systems': admin
           'fig.systems': user
   

3. Start and restart:

   docker compose up -d mautrix-whatsapp
   docker compose restart synapse
   

Using the Bridge:

1. Start chat with bot:

   • DM @whatsappbot:fig.systems in Element
   • Send: login

2. Scan QR code:

   • Bridge will send a QR code
   • Open WhatsApp on your phone
   • Go to Settings → Linked Devices → Link a Device
   • Scan the QR code

3. Chats are auto-bridged:

   • Existing WhatsApp chats appear as Matrix rooms
   • New WhatsApp messages create rooms automatically

---

6. Discord Bridge (mautrix-discord)

Purpose: Bridge Discord servers and DMs to Matrix.

Setup:

1. Generate config:

   docker compose run --rm mautrix-discord
   

2. Create Discord bot:

   • Go to https://discord.com/developers/applications
   • Create New Application
   • Go to Bot → Add Bot
   • Copy the Bot Token
   • Enable these intents:
     • Server Members Intent
     • Message Content Intent

3. Edit config:

   nano /mnt/media/matrix/bridges/discord/config.yaml
   

   Add your bot token:

   bridge:
       bot_token: YOUR_DISCORD_BOT_TOKEN
       permissions:
           '@yourusername:fig.systems': admin
           'fig.systems': user
   

4. Start and restart:

   docker compose up -d mautrix-discord
   docker compose restart synapse
   

Using the Bridge:

1. Invite bot to Discord server:

   • Get OAuth URL from bridge bot in Matrix
   • Visit URL and authorize bot for your Discord server

2. Bridge channels:

   • Create Matrix room
   • Invite @discordbot:fig.systems
   • Follow bridging instructions from bot

---

7. Google Chat Bridge (mautrix-googlechat)

Purpose: Bridge Google Chat/Hangouts to Matrix.

Setup:

Similar to other mautrix bridges:

1. Generate config: docker compose run --rm mautrix-googlechat
2. Edit /mnt/media/matrix/bridges/googlechat/config.yaml
3. Start: docker compose up -d mautrix-googlechat
4. Restart Synapse: docker compose restart synapse
5. Login via bridge bot: @googlechatbot:fig.systems

---

8. Mjolnir (Moderation Bot)

Purpose: Advanced moderation, ban lists, anti-spam protection.

Setup:

1. Create bot user:

   docker compose exec synapse register_new_matrix_user \
     -u mjolnir \
     -p <password> \
     -c /data/homeserver.yaml \
     http://localhost:8008
   

2. Create management room:

   • In Element, create a private room
   • Invite @mjolnir:fig.systems
   • Make the bot admin

3. Generate config:

   docker compose run --rm mjolnir
   

4. Edit config:

   nano /mnt/media/matrix/bridges/mjolnir/config.yaml
   

   Configure:

   homeserver: https://matrix.fig.systems
   accessToken: <get_from_login>
   managementRoom: "!roomid:fig.systems"
   

5. Get access token:

   curl -X POST https://matrix.fig.systems/_matrix/client/r0/login \
     -H "Content-Type: application/json" \
     -d '{
       "type": "m.login.password",
       "user": "mjolnir",
       "password": "<password>"
     }'
   

6. Start bot:

   docker compose up -d mjolnir
   

Using Mjolnir:

1. Protect rooms:

   • Invite Mjolnir to rooms you want to moderate
   • In management room, send: !mjolnir rooms add <room_id>

2. Subscribe to ban lists:

   • !mjolnir list subscribe <list_room_id>

3. Ban users:

   • !mjolnir ban @user:server.com

4. Commands:

   • !mjolnir help - Show all commands
   • !mjolnir status - Bot status
   • !mjolnir rooms - Protected rooms

---

9. Matrix Hookshot (GitHub/GitLab Integration)

Purpose: Receive webhooks from GitHub, GitLab, Jira in Matrix rooms.

Setup:

1. Generate config:

   docker compose run --rm hookshot
   

2. Edit config:

   nano /mnt/media/matrix/hookshot/config.yaml
   

   Key settings:

   bridge:
       domain: fig.systems
       url: https://matrix.fig.systems
       mediaUrl: https://matrix.fig.systems
       port: 9993
       bindAddress: 0.0.0.0
   
   listeners:
       - port: 9000
         bindAddress: 0.0.0.0
         resources:
           - webhooks
   
   github:
       webhook:
           secret: <random_secret>
   
   gitlab:
       webhook:
           secret: <random_secret>
   

3. Start service:

   docker compose up -d hookshot
   docker compose restart synapse
   

Using Hookshot:

For GitHub:

1. In Matrix room, invite @hookshot:fig.systems
2. Send: !github repo owner/repo
3. Bot will provide webhook URL
4. Add webhook in GitHub repo settings
5. Set webhook URL: https://hookshot.fig.systems/webhooks/github
6. Add secret from config

For GitLab: Similar process with GitLab webhooks.

Features:

• Issue notifications
• PR/MR updates
• Commit messages
• CI/CD status
• Custom filters

---

Troubleshooting

Service won't start:

# Check logs
docker compose logs <service_name>

# Check if config exists
ls -la /mnt/media/matrix/<service>/

# Regenerate config
docker compose run --rm <service_name>

Bridge not connecting:

1. Check registration file exists:

   ls -la /mnt/media/matrix/bridges/<bridge>/registration.yaml
   

2. Check Synapse can read it:

   docker compose exec synapse cat /data/bridges/<bridge>/registration.yaml
   

3. Restart Synapse:

   docker compose restart synapse
   

Can't login to admin interfaces:

• Synapse Admin: Use Matrix account credentials
• Maubot: Check /mnt/media/matrix/maubot/config.yaml for password
• Matrix Registration: Use MATRIX_REGISTRATION_ADMIN_SECRET from .env

Ports already in use:

Check what's using the port:

sudo lsof -i :<port_number>

Permission issues:

Fix ownership:

sudo chown -R 1000:1000 /mnt/media/matrix/

---

Useful Commands

# View all service logs
docker compose logs -f

# Restart all services
docker compose restart

# Update all services
docker compose pull
docker compose up -d

# Check service status
docker compose ps

# Create admin user
docker compose exec synapse register_new_matrix_user \
  -u <username> -p <password> -a -c /data/homeserver.yaml http://localhost:8008

# Backup database
docker compose exec postgres pg_dump -U synapse synapse > backup.sql

# Restore database
cat backup.sql | docker compose exec -T postgres psql -U synapse synapse

---

Next Steps

1. Set up Telegram bridge - Most useful for Telegram users
2. Create registration tokens - Invite friends/family
3. Install Maubot plugins - Add GIF search and other features
4. Configure Mjolnir - Set up moderation
5. Add GitHub webhooks - Get repo notifications in Matrix

Resources

• Matrix Documentation
• Synapse Admin Guide
• Maubot Plugins
• Bridge Setup Guides