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

```bash
cd compose/services/matrix
docker compose up -d
```

Wait for Synapse to start and initialize the database. Check logs:
```bash
docker compose logs -f synapse
```

### 2. Create Your First Admin User

Once Synapse is running, create an admin user:
```bash
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:**
```bash
# 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:**
```bash
# 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`:
```yaml
app_service_config_files:
  - /data/telegram-registration.yaml
```

Restart Synapse:
```bash
docker compose restart synapse
```

Start the bridge:
```bash
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:**
```bash
# 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:**
```bash
# 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`:
```yaml
app_service_config_files:
  - /data/telegram-registration.yaml
  - /data/whatsapp-registration.yaml
```

Restart Synapse:
```bash
docker compose restart synapse
```

Start the bridge:
```bash
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:**
```bash
# 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:**
```bash
# 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`:
```yaml
app_service_config_files:
  - /data/telegram-registration.yaml
  - /data/whatsapp-registration.yaml
  - /data/googlechat-registration.yaml
```

Restart Synapse:
```bash
docker compose restart synapse
```

Start the bridge:
```bash
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
```bash
# All services
docker compose logs -f

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

### Restart Services
```bash
# All
docker compose restart

# Specific
docker compose restart synapse
```

### Update Containers
```bash
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