sgse-app/docs/JITSI_CONFIGURACAO.md

Configuração do Jitsi Meet no SGSE

Introdução

O sistema de videochamadas do SGSE utiliza o Jitsi Meet, uma solução open-source para comunicação por vídeo e áudio. Este documento fornece um guia completo para configurar o Jitsi Meet no sistema SGSE.

Benefícios

• Chamadas de vídeo e áudio em tempo real
• Autenticação JWT para controle de acesso
• Suporte a múltiplos ambientes (desenvolvimento, staging, produção)
• Gravação de chamadas (quando habilitado no servidor)
• Integração nativa com o sistema de chat

Visão Geral da Arquitetura

┌─────────────┐         ┌──────────────┐         ┌─────────────┐
│   Cliente   │────────▶│  Backend     │────────▶│   Jitsi     │
│  (Navegador)│         │  (Convex)    │         │   Servidor  │
└─────────────┘         └──────────────┘         └─────────────┘
      │                         │                        │
      │                         │                        │
      └─────────────────────────┴────────────────────────┘
                    Token JWT (opcional)

Requisitos do Sistema

Requisitos de Hardware

• CPU: Mínimo 2 cores (recomendado: 4+ cores)
• RAM: Mínimo 4GB (recomendado: 8GB+)
• Largura de Banda: Mínimo 1 Mbps por participante (recomendado: 2+ Mbps)

Requisitos de Software

• Docker e Docker Compose (para instalação self-hosted)
• Node.js 18+ (já incluído no SGSE)
• Navegador moderno com suporte a WebRTC (Chrome, Firefox, Safari, Edge)

Requisitos de Rede

• Portas necessárias:
  • 80 (HTTP) ou 443 (HTTPS) - Web
  • 4443 (TURN/TCP) - Retransmissão de mídia
  • 10000/udp (RTP/RTCP) - Streaming de mídia
• Firewall: Permitir tráfego UDP e TCP nas portas acima
• DNS: Configurar registro A ou CNAME para o domínio (produção)

Requisitos de Certificados SSL

• Produção: Certificado válido (Let's Encrypt recomendado)
• Desenvolvimento: Certificado autoassinado aceitável

Tipos de Instalação

1. Jitsi Self-Hosted com Docker

Esta é a opção recomendada para produção e oferece controle total sobre o servidor.

Pré-requisitos

1. Servidor com Docker e Docker Compose instalados
2. Domínio configurado (para produção) ou acesso a localhost (desenvolvimento)
3. Certificado SSL (para produção)

Passo a Passo

1. Instalar Docker e Docker Compose

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install docker.io docker-compose

# Verificar instalação
docker --version
docker-compose --version

2. Criar diretório para configuração

mkdir -p ~/jitsi-meet
cd ~/jitsi-meet

3. Baixar arquivos de configuração

# Baixar docker-compose.yml oficial
curl -L https://github.com/jitsi/docker-jitsi-meet/archive/refs/heads/master.zip -o jitsi.zip
unzip jitsi.zip
cd docker-jitsi-meet-master

4. Configurar variáveis de ambiente

# Copiar arquivo de exemplo
cp env.example .env

# Editar .env com suas configurações
nano .env

Configurações importantes no .env:

# Domínio
CONFIG=~/.jitsi-meet-cfg
TZ=America/Recife
HTTP_PORT=8000
HTTPS_PORT=8443
PUBLIC_URL=https://meet.example.com
DOMAIN=meet.example.com

# Autenticação
ENABLE_AUTH=1
ENABLE_GUESTS=0

# JWT
JWT_APP_ID=sgse-app
JWT_APP_SECRET=seu-jwt-secret-aqui-minimo-32-caracteres

# Gravação (opcional)
ENABLE_RECORDING=0

# Outras configurações
ENABLE_PREJOIN_PAGE=0
START_AUDIO_MUTED=0
START_VIDEO_MUTED=0
ENABLE_XMPP_WEBSOCKET=1
ENABLE_P2P=1
MAX_NUMBER_OF_PARTICIPANTS=10

5. Gerar JWT Secret seguro

# Gerar secret aleatório de 64 caracteres
openssl rand -hex 32

6. Criar diretório de configuração

mkdir -p ~/.jitsi-meet-cfg/{web/letsencrypt,transcripts,prosody/config,prosody/prosody-plugins-custom,jicofo,jvb,jigasi,jibri}

7. Iniciar containers

docker-compose up -d

8. Verificar status

docker-compose ps

9. Verificar logs

docker-compose logs -f

Configuração de Certificados SSL

Para Produção (Let's Encrypt):

O Jitsi Docker suporta Let's Encrypt automaticamente. Configure:

ENABLE_LETSENCRYPT=1
LETSENCRYPT_DOMAIN=meet.example.com
LETSENCRYPT_EMAIL=admin@example.com

Para Desenvolvimento (Autoassinado):

ENABLE_LETSENCRYPT=0

E aceite o certificado no navegador na primeira conexão.

2. Jitsi as a Service (JaaS/8x8)

JaaS é uma solução gerenciada pela 8x8 que oferece Jitsi como serviço.

Passo a Passo

1. Criar conta no JaaS

   • Acesse https://jaas.8x8.vc
   • Crie uma conta ou faça login

2. Obter credenciais

   • No painel do JaaS, vá em "Settings" > "API Keys"
   • Copie o Application ID e Application Secret

3. Configurar no SGSE

   • Use o domínio: 8x8.vc ou seu domínio personalizado
   • App ID: O Application ID do JaaS
   • JWT Secret: O Application Secret do JaaS

4. Domínio personalizado (opcional)

   • No painel JaaS, configure um domínio personalizado
   • Atualize o domínio no SGSE

3. Desenvolvimento Local

Para desenvolvimento rápido sem Docker:

1. Usar Jitsi Meet público (não recomendado para produção)

   • Domínio: meet.jit.si
   • Não requer configuração de servidor
   • Limitações: Sem JWT, sem controle total

2. Docker local simplificado

   • Siga os passos do "Jitsi Self-Hosted"
   • Use localhost:8443 como domínio
   • Configure certificado autoassinado

Configuração de JWT no Servidor Jitsi

Para Jitsi Self-Hosted

1. Gerar JWT Secret

# Gerar secret seguro
openssl rand -hex 32

2. Configurar Prosody

Edite ~/.jitsi-meet-cfg/prosody/config/conf.d/jitsi-meet.cfg.lua:

-- Habilitar autenticação JWT
authentication = "token";

-- Configurar verificação de token
asap_accepted_audiences = "sgse-app"
asap_accepted_issuers = "sgse-app"

-- Módulo de verificação de token
Component "conference.meet.example.com" "muc"
    modules_enabled = {
        "token_verification";
    }

3. Configurar Jicofo

Edite ~/.jitsi-meet-cfg/jicofo/sip-communicator.properties:

org.jitsi.jicofo.auth.URL=XMPP:meet.example.com
org.jitsi.jicofo.jwt.secret=seu-jwt-secret-aqui
org.jitsi.jicofo.jwt.appId=sgse-app

4. Reiniciar serviços

docker-compose restart prosody jicofo

Para JaaS

JWT já está configurado. Apenas use as credenciais fornecidas no painel.

Configuração no Painel SGSE

Acesso ao Painel

1. Faça login como usuário com permissão de TI (TI_MASTER, TI_USUARIO ou ADMIN)
2. Navegue para: TI > Configurações do Jitsi

Preenchimento de Campos

Domínio

• Formato: FQDN (ex: meet.example.com) ou localhost:porta (ex: localhost:8443)
• Exemplos:
  • Produção: meet.example.com
  • Desenvolvimento: localhost:8443
  • JaaS: 8x8.vc ou seu domínio personalizado

App ID

• Formato: Alfanumérico, pode conter hífens e underscores
• Exemplos: sgse-app, my-app, app_123
• Onde encontrar:
  • Self-hosted: Configurado no .env como JWT_APP_ID
  • JaaS: Application ID no painel do JaaS

JWT Secret

• Requisitos: Mínimo 16 caracteres (recomendado: 32+)
• Onde encontrar:
  • Self-hosted: Configurado no .env como JWT_APP_SECRET
  • JaaS: Application Secret no painel do JaaS
• Segurança: O secret será criptografado antes de ser armazenado

Prefixo de Sala

• Formato: Apenas letras, números e hífens
• Exemplo: sgse, meeting, call-123
• Uso: Prefixo usado para gerar nomes únicos de salas

Ambiente

• Opções: Desenvolvimento, Staging, Produção
• Uso: Permite múltiplas configurações para diferentes ambientes
• Padrão: Deixe vazio para configuração padrão

JWT Audience e Issuer (Opcionais)

• Audience: Padrão é o domínio do servidor
• Issuer: Padrão é o App ID
• Quando configurar: Apenas se necessário para compatibilidade com configurações específicas do servidor

Teste de Conexão

1. Preencha os campos básicos (Domínio, App ID)
2. Clique em "Testar Conexão"
3. Aguarde a validação
4. Se houver erros, verifique:
   • Servidor está online
   • Domínio está correto
   • Portas estão acessíveis
   • Certificado SSL (se HTTPS)

Geração de Token de Teste

1. Configure o JWT Secret
2. Clique em "Gerar Token de Teste"
3. O token será gerado automaticamente quando você criar uma chamada

Troubleshooting

Problemas de Conexão

Servidor não acessível

Sintomas: Timeout ou erro de conexão

Soluções:

1. Verificar se o servidor está online: ping meet.example.com
2. Verificar portas: telnet meet.example.com 443
3. Verificar firewall: Permitir portas 80, 443, 4443, 10000/udp
4. Verificar DNS: nslookup meet.example.com

Timeout de conexão

Sintomas: Conexão demora muito ou falha

Soluções:

1. Verificar largura de banda
2. Verificar latência de rede
3. Verificar se há proxy ou firewall bloqueando
4. Testar de outra rede

Erro de DNS

Sintomas: "DNS resolution failed"

Soluções:

1. Verificar se o domínio está configurado corretamente
2. Verificar registros DNS (A ou CNAME)
3. Aguardar propagação DNS (até 48 horas)

Problemas de Certificado SSL

Certificado inválido

Sintomas: Aviso de certificado não confiável

Soluções:

1. Produção: Usar certificado válido (Let's Encrypt)
2. Desenvolvimento: Habilitar "Aceitar Certificados Autoassinados" no painel

Certificado autoassinado não aceito

Sintomas: Erro mesmo com opção habilitada

Soluções:

1. Aceitar certificado manualmente no navegador na primeira conexão
2. Adicionar exceção no navegador
3. Para produção, usar certificado válido

Erro de cadeia de certificados

Sintomas: "Certificate chain incomplete"

Soluções:

1. Verificar se o certificado inclui a cadeia completa
2. Reinstalar certificado com cadeia completa
3. Verificar configuração do servidor web

Problemas com JWT

Token inválido

Sintomas: Erro de autenticação ao conectar

Soluções:

1. Verificar se JWT Secret está correto no servidor e no SGSE
2. Verificar se App ID corresponde
3. Verificar se token não expirou (padrão: 1 hora)
4. Regenerar token

Token expirado

Sintomas: Conexão funciona inicialmente, depois falha

Soluções:

1. Tokens são regenerados automaticamente
2. Verificar se o relógio do servidor está sincronizado (NTP)
3. Aumentar tempo de expiração (se necessário)

Secret incorreto

Sintomas: Erro de autenticação persistente

Soluções:

1. Verificar JWT Secret no servidor (.env ou configuração)
2. Verificar JWT Secret no painel SGSE
3. Garantir que são idênticos (sem espaços extras)
4. Reiniciar serviços do Jitsi após alterar secret

Claims incorretos

Sintomas: Conexão estabelecida mas sem permissões

Soluções:

1. Verificar claims do token (iss, aud, room, moderator)
2. Verificar configuração do Prosody
3. Verificar logs do servidor Jitsi

Problemas de Firewall

Portas bloqueadas

Sintomas: Conexão HTTP funciona, mas mídia não

Soluções:

1. Abrir portas necessárias:
   • 80/tcp, 443/tcp (HTTP/HTTPS)
   • 4443/tcp (TURN)
   • 10000/udp (RTP/RTCP)
2. Verificar regras de firewall
3. Testar com telnet ou nc

UDP não funcionando

Sintomas: Áudio/vídeo cortando ou não funcionando

Soluções:

1. Verificar se UDP está habilitado no firewall
2. Verificar se NAT está configurado corretamente
3. Configurar TURN server para fallback

WebRTC bloqueado

Sintomas: Navegador não consegue estabelecer conexão WebRTC

Soluções:

1. Verificar se WebRTC está habilitado no navegador
2. Verificar se não há extensões bloqueando WebRTC
3. Verificar configurações de proxy/VPN

Problemas de Performance

Qualidade de vídeo ruim

Sintomas: Vídeo pixelado ou com baixa resolução

Soluções:

1. Verificar largura de banda disponível
2. Reduzir número de participantes simultâneos
3. Ajustar resolução nas configurações do Jitsi
4. Verificar recursos do servidor (CPU, RAM)

Áudio cortando

Sintomas: Áudio intermitente ou com atraso

Soluções:

1. Verificar latência de rede
2. Verificar recursos do servidor
3. Configurar codec de áudio adequado
4. Verificar dispositivos de áudio do cliente

Alta latência

Sintomas: Atraso perceptível entre áudio/vídeo

Soluções:

1. Verificar latência de rede (ping)
2. Verificar localização do servidor (usar servidor próximo)
3. Configurar TURN server próximo aos usuários
4. Otimizar configurações de codec

Exemplos de Configuração

Exemplo 1: Desenvolvimento Local

Domínio: localhost:8443
App ID: sgse-app
Prefixo de Sala: sgse-dev
HTTPS: Sim
Certificados Autoassinados: Sim
JWT Secret: (opcional para desenvolvimento)
Ambiente: desenvolvimento

Exemplo 2: Produção Self-Hosted

Domínio: meet.example.com
App ID: sgse-app
Prefixo de Sala: sgse
HTTPS: Sim
Certificados Autoassinados: Não
JWT Secret: [secret de 32+ caracteres]
JWT Audience: meet.example.com
JWT Issuer: sgse-app
Ambiente: producao

Exemplo 3: JaaS com Domínio Personalizado

Domínio: meet.seudominio.com
App ID: [Application ID do JaaS]
Prefixo de Sala: sgse
HTTPS: Sim
Certificados Autoassinados: Não
JWT Secret: [Application Secret do JaaS]
Ambiente: producao

Exemplo 4: Múltiplos Ambientes

Desenvolvimento:

Ambiente: desenvolvimento
Domínio: localhost:8443

Staging:

Ambiente: staging
Domínio: meet-staging.example.com

Produção:

Ambiente: producao
Domínio: meet.example.com

Boas Práticas

Segurança

1. Use HTTPS em produção: Sempre use certificados válidos
2. JWT Secret forte: Mínimo 32 caracteres, use gerador seguro
3. Rotação de secrets: Rotacione JWT secrets periodicamente
4. Limitação de acesso: Configure firewall para permitir apenas IPs necessários (opcional)
5. Logs de auditoria: Monitore logs para atividades suspeitas

Performance

1. Recursos do servidor: Aloque recursos adequados (CPU, RAM, largura de banda)
2. Otimização de codecs: Use codecs eficientes (VP8, Opus)
3. Configuração de P2P: Habilite P2P para reduzir carga no servidor
4. Monitoramento: Monitore métricas de CPU, RAM, largura de banda

Monitoramento

1. Logs importantes:

   • Logs do Prosody (XMPP)
   • Logs do Jicofo (conferências)
   • Logs do JVB (vídeo bridge)
   • Logs do nginx (web server)

2. Métricas a acompanhar:

   • Número de participantes ativos
   • Largura de banda utilizada
   • CPU e RAM do servidor
   • Latência de conexão

3. Alertas recomendados:

   • Alta utilização de CPU/RAM
   • Falhas de conexão
   • Certificados próximos do vencimento
   • Erros de autenticação JWT

Referências

• Documentação oficial do Jitsi Meet: https://jitsi.github.io/handbook/
• Especificação JWT do Jitsi: https://github.com/jitsi/lib-jitsi-meet/blob/master/doc/tokens.md
• Guia de instalação Docker: https://jitsi.github.io/handbook/docs/devops-guide/devops-guide-docker
• Comunidade Jitsi: https://community.jitsi.org/
• JaaS (8x8): https://jaas.8x8.vc

Suporte

Para problemas ou dúvidas:

1. Consulte a seção de Troubleshooting acima
2. Verifique os logs do servidor Jitsi
3. Consulte a documentação oficial do Jitsi
4. Entre em contato com a equipe de TI