# La Suite Meet — Test Documentation

## Test instance

- **Domain:** lasuite-meet.<DOMAIN_SUFFIX>
- **LiveKit domain:** livekit-meet.<DOMAIN_SUFFIX>
- **Keycloak:** keycloak.<DOMAIN_SUFFIX> (shared with other lasuite recipes)

## Services

| Service | Health check | Notes |
|---------|-------------|-------|
| app (frontend) | curl http://localhost:8080 | React SPA served by nginx |
| backend | python manage.py check | Django + Gunicorn on port 8000 |
| celery | celery inspect ping | Async task worker |
| db | pg_isready | PostgreSQL 18 |
| redis | redis-cli ping | Cache + Celery broker + LiveKit coordination |
| livekit | N/A (external ports) | WebRTC SFU on 7880 (signaling), 7881 (TCP), 7882 (UDP) |
| web (nginx) | curl http://localhost:8083 | Reverse proxy |

## Automated tests

| Script | What it tests |
|--------|--------------|
| `tests/health_check.py` | HTTP 200 from the main domain |
| `tests/oidc_login.py` | Full OIDC flow: redirect to Keycloak, obtain token, call API |
| `tests/meeting_flow.py` | Two users create, join, and delete a room; verifies LiveKit tokens |
| `tests/webrtc-media.py` | End-to-end WebRTC: TURN/STUN probe, two users publish/receive audio via LiveKit SDK |

### Network requirements for webrtc-media.py

The WebRTC media test requires:
- Python 3 with `livekit` and `requests` packages (`pip install livekit requests`)
- Either direct ICE connectivity (TCP 7881 / UDP 7882) or TURN relay (UDP 443)
- With TURN enabled, clients behind CGNAT/symmetric NAT can connect via relay

## Manual checks

- Visit `https://lasuite-meet.<DOMAIN_SUFFIX>` — should show Meet login page
- Click login — should redirect to Keycloak
- After OIDC login — should be able to create/join a meeting room
- Check LiveKit signaling: `wss://livekit-meet.<DOMAIN_SUFFIX>` should be reachable

## TURN server

TURN is enabled by default via `compose.turn.yml` and `LIVEKIT_TURN_ENABLED=true`. It publishes UDP 443 on the host for TURN relay traffic, improving connectivity for users behind CGNAT/symmetric NAT.

### Verifying TURN

1. Check LiveKit logs for TURN startup:
   ```bash
   ssh <server> "docker service logs <stack>_livekit --since 5m 2>&1 | grep -i turn"
   ```
2. Verify UDP 443 is listening on the server:
   ```bash
   ssh <server> "ss -ulnp | grep 443"
   ```
3. Run `webrtc-media.py` — it sends a STUN Binding Request to UDP 443 and verifies a response
4. Check LiveKit logs for `connectionType` to confirm relay vs direct ICE

### Disabling TURN

Remove `compose.turn.yml` from `COMPOSE_FILE` in the app `.env` and set `LIVEKIT_TURN_ENABLED=false`.

### TURN and servers behind NAT

LiveKit's built-in TURN server requires the server to have a **direct public IP**. On servers behind NAT (where `LIVEKIT_NODE_IP` is the gateway's public IP, not the server's own), TURN relay traffic hits a "hairpin NAT" problem: the TURN relay inside the container sends to the public IP, but the packet exits through the NAT gateway which doesn't route it back.

**Symptoms:** TURN allocations succeed (relay candidates appear in LiveKit logs), but ICE connection never succeeds (`connectionType: "unknown"`).

**Workaround for NAT servers:** Use an external TURN server (e.g., coturn) instead of LiveKit's built-in TURN, or configure the NAT gateway to do hairpin NAT for the relay ports.

## Dependencies

- Keycloak must be deployed and configured (run `setup_keycloak_integration.py`)
- Firewall must allow TCP 7881 and UDP 7882 on the server
- For TURN: firewall must also allow UDP 443 and UDP 30000-30009 (relay ports)