# Element Call + LiveKit en este stack

Esta guía resume cómo se conecta el repositorio `element-call` incluido en este
proyecto y qué pasos seguir para habilitar el backend MatrixRTC (LiveKit +
lk-jwt-service) dentro del entorno Docker ya existente.

> ℹ️  Para más contexto técnico revisa también `element-call/docs/self-hosting.md`
> y `element-call/backend/dev_nginx.conf`, donde Element documenta la arquitectura
> oficial de referencia.

## 1. Requisitos del homeserver

1. Añade las MSC necesarias en `synapse_data/homeserver.yaml` (o en tu plantilla):

   ```yaml
   experimental_features:
     msc3266_enabled: true
     msc4222_enabled: true
     msc4354_enabled: true

   max_event_delay_duration: 24h

   rc_message:
     per_second: 0.5
     burst_count: 30

   rc_delayed_event_mgmt:
     per_second: 1
     burst_count: 20
   ```

2. Asegúrate de tener un listener `federation` o `openid` expuesto (lo necesita
   el `lk-jwt-service` para validar los tokens Matrix).

3. Configura `.well-known/matrix/client` para publicar el backend MatrixRTC:

   ```json
   {
     "m.homeserver": {
       "base_url": "https://matrix.example.com",
       "server_name": "matrix.example.com"
     },
     "org.matrix.msc4143.rtc_foci": [
       {
         "type": "livekit",
         "livekit_service_url": "https://matrix-rtc.example.com/livekit/jwt"
       }
     ]
   }
   ```

   El archivo `configs/well-known/matrix-client.example.json` sirve como plantilla;
   cópialo a `configs/well-known/matrix-client.json` y ajústalo con tu dominio.
   Sirve este JSON con TLS (Nginx/Caddy) en `https://<tu-dominio>/.well-known/matrix/client`.

## 2. Preparar configuraciones locales

1. **Variables de entorno**  
   Edita `.env` (o crea uno nuevo desde `.env.example`) y completa los valores:
   - `MATRIX_SITE_BASE_URL`, `MATRIX_RTC_BASE_URL`
   - `LIVEKIT_WS_URL`, `LIVEKIT_JWT_URL`
   - `LIVEKIT_API_KEY`, `LIVEKIT_API_SECRET`
   - Puertos `LIVEKIT_*`

2. **LiveKit**  
   - Copia `configs/livekit/livekit.example.yaml` a
     `configs/livekit/livekit.yaml`.
   - Cambia región, puertos si es necesario y, sobre todo, define tu par
     `keys` con el mismo `LIVEKIT_API_KEY`/`LIVEKIT_API_SECRET` del `.env`.

3. **Reverse proxy**  
   Expón dos rutas públicas (con TLS) hacia los nuevos contenedores:

   | Ruta pública                                | Proxy interno                       |
   | ------------------------------------------- | ----------------------------------- |
   | `https://matrix-rtc.example.com/livekit/jwt` | `http://livekit-jwt:${LIVEKIT_JWT_PORT}` |
   | `wss://matrix-rtc.example.com/livekit/sfu`   | `http://livekit:${LIVEKIT_HTTP_PORT}`    |

   Ejemplo básico en Nginx:

   ```nginx
   server {
       server_name matrix-rtc.example.com;
       listen 443 ssl http2;

       location ^~ /livekit/jwt/ {
           proxy_pass http://10.10.10.7:${LIVEKIT_JWT_PORT}/;
           proxy_set_header Host $host;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }

       location ^~ /livekit/sfu/ {
           proxy_pass http://10.10.10.6:${LIVEKIT_HTTP_PORT}/;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_read_timeout 120;
           proxy_send_timeout 120;
       }
   }
   ```

## 3. Desplegar los servicios LiveKit

1. Levanta la red base y los servicios habituales (`docker-compose up -d`).
2. Arranca los componentes MatrixRTC usando el archivo adicional:

   ```bash
   docker compose -f docker-compose.yml -f docker-compose.livekit.yml up -d livekit livekit-jwt
   ```

   El archivo `docker-compose.livekit.yml` añade:
   - `livekit`: SFU oficial (`livekit/livekit-server`) usando `configs/livekit/livekit.yaml`.
   - `livekit-jwt`: servicio `ghcr.io/element-hq/lk-jwt-service` que firma los
     tokens que consumen los clientes MatrixRTC.

3. Comprueba que los servicios responden:

   ```bash
   # JWT service
   curl -sf https://matrix-rtc.example.com/livekit/jwt/healthz

   # LiveKit (revisa los logs o escucha el puerto de salud configurado)
   docker logs -f element_matrix_chat-livekit-1
   ```

## 4. Publicar el frontend Element Call (opcional)

El backend LiveKit habilita las llamadas MatrixRTC para Element Web / Element X
una vez que el `.well-known` anuncia el foco. Si además quieres exponer la
aplicación Element Call en modo standalone:

1. Construye el frontend:

   ```bash
   cd element-call
   corepack enable
   yarn install --immutable
   cp config/config.sample.json public/config.json   # o personaliza uno nuevo
   yarn build
   ```

2. Sirve los archivos de `element-call/dist/` con el servidor web de tu
preferencia (o crea tu propia imagen Docker basada en `element-call/Dockerfile`).
Recuerda actualizar `public/config.json` para apuntar a tu homeserver y, si lo
quieres forzar, al `livekit_service_url`.

## 5. Verificación final

1. Abre `https://matrix.example.com/.well-known/matrix/client` y valida que el
   JSON devuelve correctamente tu `livekit_service_url`.
2. Desde Element Web (usuario registrado en el mismo homeserver) inicia una
   llamada en una sala y revisa en los logs del contenedor `livekit-jwt`
   que se emite el token (`docker logs -f <contenedor>`).
3. Usa herramientas como [testmatrix](https://codeberg.org/spaetz/testmatrix) para
   validar que tu sitio expone MatrixRTC correctamente.

Con estos pasos tendrás tanto el backend MatrixRTC (LiveKit + Authorization
Service) como la referencia para desplegar el frontend Element Call dentro de
tu servidor Matrix.