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:**
   ```bash
   cd /home/eduardo_figueroa/homelab/compose/services/matrix
   docker compose up -d
   ```

2. **Check service health:**
   ```bash
   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:**
   ```bash
   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:

```bash
# 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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   docker compose run --rm mautrix-telegram
   ```

3. **Edit config:**
   ```bash
   nano /mnt/media/matrix/bridges/telegram/config.yaml
   ```

   Key settings:
   ```yaml
   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:**
   ```bash
   docker compose up -d mautrix-telegram
   ```

5. **Restart Synapse** (to load the registration file):
   ```bash
   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:**
   ```bash
   docker compose run --rm mautrix-whatsapp
   ```

2. **Edit config:**
   ```bash
   nano /mnt/media/matrix/bridges/whatsapp/config.yaml
   ```

   Update:
   ```yaml
   homeserver:
       address: http://synapse:8008
       domain: fig.systems

   bridge:
       permissions:
           '@yourusername:fig.systems': admin
           'fig.systems': user
   ```

3. **Start and restart:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   nano /mnt/media/matrix/bridges/discord/config.yaml
   ```

   Add your bot token:
   ```yaml
   bridge:
       bot_token: YOUR_DISCORD_BOT_TOKEN
       permissions:
           '@yourusername:fig.systems': admin
           'fig.systems': user
   ```

4. **Start and restart:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   docker compose run --rm mjolnir
   ```

4. **Edit config:**
   ```bash
   nano /mnt/media/matrix/bridges/mjolnir/config.yaml
   ```

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

5. **Get access token:**
   ```bash
   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:**
   ```bash
   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:**
   ```bash
   docker compose run --rm hookshot
   ```

2. **Edit config:**
   ```bash
   nano /mnt/media/matrix/hookshot/config.yaml
   ```

   Key settings:
   ```yaml
   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:**
   ```bash
   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:

```bash
# 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:
   ```bash
   ls -la /mnt/media/matrix/bridges/<bridge>/registration.yaml
   ```

2. Check Synapse can read it:
   ```bash
   docker compose exec synapse cat /data/bridges/<bridge>/registration.yaml
   ```

3. Restart Synapse:
   ```bash
   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:
```bash
sudo lsof -i :<port_number>
```

### Permission issues:

Fix ownership:
```bash
sudo chown -R 1000:1000 /mnt/media/matrix/
```

---

## Useful Commands

```bash
# 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](https://matrix.org/docs/)
- [Synapse Admin Guide](https://element-hq.github.io/synapse/latest/)
- [Maubot Plugins](https://github.com/maubot/maubot/wiki/Plugin-directory)
- [Bridge Setup Guides](https://docs.mau.fi/bridges/)