---
id: "0166"
title: "Desplegar TURN para LiveKit (coturn o integrado)"
status: pendiente
type: infra
domain:
  - matrix
scope: app:element_matrix_chat
priority: alta
depends: []
blocks: []
related: ["0167", "0168"]
created: 2026-05-24
updated: 2026-05-24
tags: [matrix, livekit, webrtc, turn, nat]
---
# 0166 — Desplegar TURN para LiveKit (coturn o integrado)

**Status:** pendiente
**Created:** 2026-05-24
**Type:** infra
**Priority:** alta
**Domain:** matrix
**Scope:** app:element_matrix_chat
**Depends:** —
**Blocks:** —

## Problema

LiveKit corre sin TURN (`turn.enabled: false` en `configs/livekit/livekit.yaml`). Usuarios detras de NAT simetrico (CGNAT movil 4G/5G, redes corporativas con firewall estricto, hotel WiFi) NO pueden establecer call — WebRTC ICE direct/reflexive falla. Calls fallan silenciosos para ~10-20% usuarios.

## Objetivo

Calls funcionan en cualquier red. Element X movil sobre 4G CGNAT completa handshake.

## Plan

1. Decidir: coturn standalone vs LiveKit TURN integrado (recomendado: integrado, menos moving parts).
2. Anadir subdominio `turn.organic-machine.com` con Let's Encrypt cert (Traefik).
3. Activar bloque `turn:` en `livekit.yaml`:
   ```yaml
   turn:
     enabled: true
     domain: "turn.organic-machine.com"
     tls_port: 5349
     udp_port: 443
     external_tls: true
   ```
4. Abrir puertos VPS firewall: TCP+UDP 443 (best practice — bypassea firewalls corp), TCP 5349.
5. Rotar shared secret TURN.
6. Test: navegador en red corp con `force-tcp` flag → call establecida.

## Acceptance

- [ ] `nc -vz turn.organic-machine.com 443` UDP+TCP OK.
- [ ] Test call Element Web detras de NAT simetrico (movil hotspot tethering) → audio/video pasa.
- [ ] LiveKit logs muestran `TURN allocation` requests servidas.
- [ ] `.well-known/matrix/client` sigue apuntando al `livekit_service_url` JWT correcto.

## Definition of Done

- [ ] Repetibilidad: 5 calls consecutivas desde 5 redes distintas (incluido CGNAT) sin fallo.
- [ ] Observabilidad: dashboard LiveKit muestra TURN vs direct ratio.
- [ ] User-facing: usuario movil 4G inicia call → conecta < 3s.

## Notas

UDP 443 es trick conocido: la mayoria de firewalls corporativos solo dejan 443 (HTTPS) — TURN sobre UDP 443 bypassea sin requerir TCP relay que aumenta latencia.

Alternativa coturn standalone si LiveKit integrado tiene gaps de gestion: `docker run -d coturn/coturn` + config compartida con shared secret de LiveKit.