homelab/compose/services/matrix/README.md

Matrix Server with Bridges

Complete Matrix/Synapse homeserver setup with local authentication and bridges for Telegram, WhatsApp, and Google Chat.

Architecture

• Synapse: Matrix homeserver (fig.systems)
• PostgreSQL: Database backend
• Traefik: Reverse proxy with Let's Encrypt
• Bridges: Telegram, WhatsApp, Google Chat
• Optional: Element web client

Domain Configuration

• Server: matrix.fig.systems
• Server Name: fig.systems (used for Matrix IDs like @user:fig.systems)
• Federation: Enabled via .well-known delegation

Setup Instructions

1. Deploy Matrix Server

cd compose/services/matrix
docker compose up -d

Wait for Synapse to start and initialize the database. Check logs:

docker compose logs -f synapse

2. Create Your First Admin User

Once Synapse is running, create an admin user:

docker exec -it matrix-synapse register_new_matrix_user -c /data/homeserver.yaml -a http://localhost:8008

Follow the prompts to create your admin account with a username and password.

3. Test Matrix Server

Visit https://matrix.fig.systems and you should see the Matrix homeserver info.

Try logging in:

1. Go to https://app.element.io
2. Click "Sign in"
3. Click "Edit" next to the homeserver
4. Enter: matrix.fig.systems
5. Click "Continue"
6. Enter your username and password

4. Configure Telegram Bridge

Get Telegram API Credentials:

1. Visit https://my.telegram.org
2. Log in with your phone number
3. Go to "API development tools"
4. Create an app (use any title/short name)
5. Note your api_id (number) and api_hash (string)

Generate Bridge Config:

# Generate initial config
docker run --rm -v /mnt/media/matrix/bridges/telegram:/data dock.mau.dev/mautrix/telegram:latest

# Edit the config
nano /mnt/media/matrix/bridges/telegram/config.yaml

Update these settings in config.yaml:

• homeserver.address: http://synapse:8008
• homeserver.domain: fig.systems
• appservice.address: http://mautrix-telegram:29317
• appservice.hostname: 0.0.0.0
• appservice.port: 29317
• appservice.database: postgres://synapse:PASSWORD@postgres/telegram (use password from .env)
• telegram.api_id: Your API ID
• telegram.api_hash: Your API hash
• bridge.permissions: Add your Matrix ID with admin level

Register the bridge:

# Copy the registration file to Synapse
cp /mnt/media/matrix/bridges/telegram/registration.yaml /mnt/media/matrix/synapse/data/telegram-registration.yaml

Add to homeserver.yaml under app_service_config_files:

app_service_config_files:
  - /data/telegram-registration.yaml

Restart Synapse:

docker compose restart synapse

Start the bridge:

docker compose up -d mautrix-telegram

Use the bridge:

1. In Element, start a chat with @telegrambot:fig.systems
2. Send login and follow the instructions

5. Configure WhatsApp Bridge

Generate Bridge Config:

# Generate initial config
docker run --rm -v /mnt/media/matrix/bridges/whatsapp:/data dock.mau.dev/mautrix/whatsapp:latest

# Edit the config
nano /mnt/media/matrix/bridges/whatsapp/config.yaml

Update these settings in config.yaml:

• homeserver.address: http://synapse:8008
• homeserver.domain: fig.systems
• appservice.address: http://mautrix-whatsapp:29318
• appservice.hostname: 0.0.0.0
• appservice.port: 29318
• appservice.database.uri: postgres://synapse:PASSWORD@postgres/whatsapp (use password from .env)
• bridge.permissions: Add your Matrix ID with admin level

Register the bridge:

# Copy the registration file to Synapse
cp /mnt/media/matrix/bridges/whatsapp/registration.yaml /mnt/media/matrix/synapse/data/whatsapp-registration.yaml

Add to homeserver.yaml:

app_service_config_files:
  - /data/telegram-registration.yaml
  - /data/whatsapp-registration.yaml

Restart Synapse:

docker compose restart synapse

Start the bridge:

docker compose up -d mautrix-whatsapp

Use the bridge:

1. In Element, start a chat with @whatsappbot:fig.systems
2. Send login
3. Scan the QR code with WhatsApp on your phone (like WhatsApp Web)

6. Configure Google Chat Bridge

Prerequisites:

• Google Cloud Project
• Google Chat API enabled
• OAuth 2.0 credentials

Setup Google Cloud:

1. Go to https://console.cloud.google.com
2. Create a new project or select existing
3. Enable "Google Chat API"
4. Create OAuth 2.0 credentials:
   • Application type: Desktop app
   • Download the JSON file

Generate Bridge Config:

# Generate initial config
docker run --rm -v /mnt/media/matrix/bridges/googlechat:/data dock.mau.dev/mautrix/googlechat:latest

# Edit the config
nano /mnt/media/matrix/bridges/googlechat/config.yaml

Update these settings in config.yaml:

• homeserver.address: http://synapse:8008
• homeserver.domain: fig.systems
• appservice.address: http://mautrix-googlechat:29319
• appservice.hostname: 0.0.0.0
• appservice.port: 29319
• appservice.database: postgres://synapse:PASSWORD@postgres/googlechat (use password from .env)
• bridge.permissions: Add your Matrix ID with admin level

Register the bridge:

# Copy the registration file to Synapse
cp /mnt/media/matrix/bridges/googlechat/registration.yaml /mnt/media/matrix/synapse/data/googlechat-registration.yaml

Add to homeserver.yaml:

app_service_config_files:
  - /data/telegram-registration.yaml
  - /data/whatsapp-registration.yaml
  - /data/googlechat-registration.yaml

Restart Synapse:

docker compose restart synapse

Start the bridge:

docker compose up -d mautrix-googlechat

Use the bridge:

1. In Element, start a chat with @googlechatbot:fig.systems
2. Send login
3. Follow the OAuth flow to authenticate with your Google account

Note for Work Google Chat: Your organization's Google Workspace admin might need to approve the OAuth app.

Client Apps

Element (Recommended)

Web: https://app.element.io iOS: https://apps.apple.com/app/element-messenger/id1083446067 Android: https://play.google.com/store/apps/details?id=im.vector.app

Setup:

1. Open Element
2. Click "Sign in"
3. Click "Edit" next to homeserver
4. Enter: matrix.fig.systems
5. Click "Continue"
6. Enter your username and password

Alternative Clients

• FluffyChat: Modern, lightweight client
• SchildiChat: Element fork with UI improvements
• Nheko: Desktop client

All clients work by pointing to matrix.fig.systems as the homeserver.

Maintenance

View Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f synapse
docker compose logs -f mautrix-telegram

Restart Services

# All
docker compose restart

# Specific
docker compose restart synapse

Update Containers

docker compose pull
docker compose up -d

Backup

Important directories:

• /mnt/media/matrix/synapse/data - Synapse configuration and signing keys
• /mnt/media/matrix/synapse/media - Uploaded media files
• /mnt/media/matrix/postgres - Database
• /mnt/media/matrix/bridges/ - Bridge configurations

Troubleshooting

Can't connect to homeserver

• Check Synapse logs: docker compose logs synapse
• Verify Traefik routing: docker compose -f compose/core/traefik/compose.yaml logs
• Test endpoint: curl -k https://matrix.fig.systems/_matrix/client/versions

Login not working

• Verify you created a user with register_new_matrix_user
• Check Synapse logs for authentication errors
• Ensure the homeserver is set to matrix.fig.systems in your client

Bridge not connecting

• Check bridge logs: docker compose logs mautrix-telegram
• Verify registration file is in Synapse config
• Ensure bridge database is created in PostgreSQL
• Restart Synapse after adding registration files

Federation issues

• Ensure ports 80 and 443 are accessible
• Check .well-known delegation is working
• Test federation: https://federationtester.matrix.org/

Security Notes

• Users authenticate with local Matrix passwords
• Public registration is disabled (use register_new_matrix_user to create accounts)
• Federation uses standard HTTPS (443) with .well-known delegation
• All bridges run on internal network only
• Media uploads limited to 50MB

Configuration Files

• compose.yaml - Docker Compose configuration
• homeserver.yaml - Synapse configuration
• .env - Environment variables and secrets

Resources

• Matrix Documentation: https://matrix.org/docs/
• Synapse Documentation: https://element-hq.github.io/synapse/latest/
• Mautrix Bridges: https://docs.mau.fi/bridges/
• Element Help: https://element.io/help