recipe-maintainer: public snapshot (secrets + deployment plans removed, single commit)

Sanitized single-commit public mirror of recipe-maintainer. - Removed test-ssh/.testenv (live creds); added test-ssh/.testenv.example placeholders. - Removed plans/ and planned-updates/ (deployment-planning docs) so no client/ deployment domains appear in the public repo. - All other secret stores were already gitignored. - docs.coopcloud.tech retained as a submodule (public upstream).
2026-06-16 20:18:24 +00:00
commit f283a371bb
253 changed files with 15975 additions and 0 deletions
@@ -0,0 +1,77 @@
+# 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)