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

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

Wait ~30 seconds for database initialization. Watch logs:
```bash
docker compose logs -f synapse
```

Look for: `Synapse now listening on port 8008`

## Step 2: Create Admin User

Create your first admin account:
```bash
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
```bash
# 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:**
```yaml
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
```bash
# 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

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

```bash
# 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/