homelab/compose/services/matrix/QUICKSTART.md

Matrix Quick Start Guide

Get your Matrix server running in 4 steps!

Before You Start

You'll need:

1. Telegram API credentials (see step 3)

Step 1: Start Matrix Server

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

Wait ~30 seconds for database initialization. Watch logs:

docker compose logs -f synapse

Look for: Synapse now listening on port 8008

Step 2: Create Admin User

Create your first admin account:

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

Follow the prompts to enter a username and password.

Your Matrix ID will be: @yourusername:fig.systems

Step 3: Test Login via Element

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

Step 4: Set Up Telegram Bridge

Get API Credentials

1. Visit https://my.telegram.org (login with phone)
2. "API development tools" → Create app
3. Save your api_id and api_hash

Configure Bridge

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

# Edit config (use your favorite editor)
sudo nano /mnt/media/matrix/bridges/telegram/config.yaml

Key settings to update:

homeserver:
    address: http://synapse:8008
    domain: fig.systems

appservice:
    address: http://mautrix-telegram:29317
    database: postgres://synapse:46d8cb2e8bdacf5a267a5f35bcdea4ded46e42ced008c4998e180f33e3ce07c5@postgres/telegram

telegram:
    api_id: YOUR_API_ID_HERE
    api_hash: YOUR_API_HASH_HERE

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

Register and Start

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

# Add to homeserver.yaml (add these lines at the end)
echo "
app_service_config_files:
  - /data/telegram-registration.yaml" | sudo tee -a homeserver.yaml

# Restart and start bridge
docker compose restart synapse
docker compose up -d mautrix-telegram

Use the Bridge

In Element:

1. Start chat with @telegrambot:fig.systems
2. Type: login
3. Follow the instructions

Step 5: Set Up WhatsApp Bridge

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

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

Key settings:

homeserver:
    address: http://synapse:8008
    domain: fig.systems

appservice:
    address: http://mautrix-whatsapp:29318
    database:
        uri: postgres://synapse:46d8cb2e8bdacf5a267a5f35bcdea4ded46e42ced008c4998e180f33e3ce07c5@postgres/whatsapp

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

Register and Start

# Copy registration
sudo cp /mnt/media/matrix/bridges/whatsapp/registration.yaml \
  /mnt/media/matrix/synapse/data/whatsapp-registration.yaml

# Update homeserver.yaml
sudo nano homeserver.yaml
# Add to app_service_config_files:
#   - /data/whatsapp-registration.yaml

# Restart and start bridge
docker compose restart synapse
docker compose up -d mautrix-whatsapp

Use the Bridge

In Element:

1. Start chat with @whatsappbot:fig.systems
2. Type: login
3. Scan QR code with your phone

Optional: Google Chat Bridge

Google Chat requires additional Google Cloud setup (OAuth credentials).

See full README.md for detailed instructions.

Quick Commands

# View all logs
docker compose logs -f

# View specific service logs
docker compose logs -f synapse
docker compose logs -f mautrix-telegram

# Restart everything
docker compose restart

# Stop everything
docker compose down

# Update containers
docker compose pull && docker compose up -d

Verify Everything Works

Test Checklist

• Can login at https://app.element.io with username/password
• Can send messages in Element
• Telegram bridge responds to commands
• WhatsApp bridge shows QR code
• Can see Telegram/WhatsApp chats in Element after bridging

Troubleshooting

Can't login

• Check Synapse logs: docker compose logs synapse | grep -i error
• Verify you created a user with register_new_matrix_user
• Test endpoint: curl https://matrix.fig.systems/_matrix/client/versions

Bridge not working

• Check bridge logs: docker compose logs mautrix-telegram
• Verify registration file path in homeserver.yaml
• Ensure Synapse was restarted after adding registration
• Check bridge can reach Synapse: docker compose exec mautrix-telegram ping synapse

Next Steps

• Invite friends to your Matrix server
• Create encrypted rooms for private conversations
• Bridge more Telegram/WhatsApp chats
• Set up Google Chat bridge for work communications
• Install Element on your phone for mobile access

Need Help?

See README.md for:

• Detailed configuration explanations
• Google Chat bridge setup
• Federation troubleshooting
• Backup procedures
• Advanced configurations

Matrix documentation: https://matrix.org/docs/ Mautrix bridges: https://docs.mau.fi/bridges/