# TURN Server Setup for GLETRA WebRTC Calls

WebRTC audio/video calls use peer-to-peer connections. **STUN** helps discover public IP addresses; **TURN** relays media when direct P2P fails (strict NAT, corporate firewalls, mobile networks).

GLETRA ships with Google STUN servers. For reliable production calling, add your own TURN server.

## Enable TURN in GLETRA

Add to `.env`:

```env
TURN_ENABLED=true
TURN_URL=turn:turn.yourdomain.com:3478
TURN_USERNAME=gletra
TURN_CREDENTIAL=your_strong_secret
```

Restart Laravel and rebuild assets if needed. ICE servers are returned from `/calls/initiate` and `/calls/{id}/accept`.

## Option 1 — coturn (recommended, self-hosted)

Install on Ubuntu/Debian:

```bash
sudo apt update
sudo apt install coturn
```

Edit `/etc/turnserver.conf`:

```ini
listening-port=3478
tls-listening-port=5349
fingerprint
lt-cred-mech
user=gletra:your_strong_secret
realm=yourdomain.com
total-quota=100
stale-nonce=600
cert=/etc/letsencrypt/live/turn.yourdomain.com/fullchain.pem
pkey=/etc/letsencrypt/live/turn.yourdomain.com/privkey.pem
no-cli
no-loopback-peers
no-multicast-peers
```

Enable and start:

```bash
sudo systemctl enable coturn
sudo systemctl restart coturn
```

Firewall:

```bash
sudo ufw allow 3478/tcp
sudo ufw allow 3478/udp
sudo ufw allow 5349/tcp
sudo ufw allow 5349/udp
sudo ufw allow 49152:65535/udp
```

GLETRA `.env`:

```env
TURN_ENABLED=true
TURN_URL=turn:turn.yourdomain.com:3478
TURN_USERNAME=gletra
TURN_CREDENTIAL=your_strong_secret
```

For TLS TURN:

```env
TURN_URL=turns:turn.yourdomain.com:5349
```

## Option 2 — Docker coturn

```yaml
# docker-compose.turn.yml
services:
  coturn:
    image: coturn/coturn:latest
    network_mode: host
    volumes:
      - ./turnserver.conf:/etc/coturn/turnserver.conf:ro
    restart: unless-stopped
```

## Option 3 — Shared TURN on same VPS as GLETRA

If GLETRA runs on `gletra.com`, use subdomain `turn.gletra.com`:

1. DNS A record → same VPS IP
2. SSL cert for `turn.gletra.com`
3. coturn on ports 3478/5349
4. Nginx does **not** proxy TURN — coturn listens directly

## Verify TURN works

1. Open [WebRTC Trickle ICE](https://webrtc.github.io/samples/src/content/peerconnection/trickle-ice/)
2. Add your TURN server with username/credential
3. Gather candidates — you should see `relay` type candidates

Or test a call between:
- User on mobile LTE
- User on corporate WiFi

Without TURN, one side often fails to connect.

## Security notes

- Use strong TURN credentials (rotate periodically)
- Restrict `user=` accounts in coturn
- Do not expose coturn admin CLI publicly
- Monitor bandwidth — TURN relays all media through your server

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Calls work on WiFi but not mobile | Enable TURN |
| `TURN_ENABLED=true` but no relay | Check firewall UDP ports |
| Credential rejected | Match username/password in coturn and `.env` |
| TLS TURN fails | Valid cert on coturn; use `turns:` URL |

## Cost estimate

TURN bandwidth ≈ 2× call bitrate × duration × participants (for relayed calls).

Example: 64 kbps audio × 2 directions × 10 min ≈ 9.6 MB per relayed call.

Video (500 kbps) uses significantly more — plan capacity accordingly.