Solución de problemas

Un contenedor no arranca

docker compose -f infra/docker-compose.yml logs api (o worker, web, migrate) es siempre el primer lugar para mirar. api y worker validan todas las variables de entorno requeridas al iniciar y reportan todo lo que falta o está mal formado en un único mensaje — no se detienen en la primera variable faltante y te obligan a un ciclo de arreglar-reiniciar- descubrir-la-siguiente.

"this self-hosted instance already has a tenant"

Estás en SEREDINA_MODE=self_hosted (el modo por defecto, pensado para una sola organización) e intentaste registrar una segunda. Si de verdad necesitas múltiples organizaciones independientes, es modo cloud, no self-hosted.

ENCRYPTION_KEY inválida

Tiene que ser exactamente 64 caracteres hexadecimales (32 bytes) — genérala con openssl rand -hex 32. Un valor más corto, más largo, o con caracteres fuera de 0-9a-f hace que api rechace arrancar con un mensaje explícito señalando esta variable.

El copiloto de IA responde 503

Es el comportamiento esperado sin un proveedor de IA configurado — no es un error de instalación. Revisa AI_PROVIDER y la clave correspondiente (ANTHROPIC_API_KEY, OPENAI_API_KEY, o que OLLAMA_BASE_URL apunte a una instancia de Ollama corriendo de verdad) en Variables de entorno. También revisa que el tenant no tenga su propia clave configurada en Ajustes → IA que esté mal — si el tenant tiene una clave propia, se usa en vez de la del despliegue, nunca como respaldo.

Telegram no entrega mensajes

API_PUBLIC_URL tiene que ser una URL HTTPS real, alcanzable desde internet — Telegram la llama directamente para entregar cada mensaje, así que localhost o un hostname interno de Docker Compose nunca va a funcionar. Si estás probando en local sin un dominio público, Telegram no es viable todavía; usa un canal de correo o la API en su lugar.

Un canal de correo dejó de sincronizar

Empieza por Canales de correo: ahí se ve el último error de inicio de sesión de cada buzón.

• "Requiere reconexión" en un canal de Microsoft 365 o Gmail: el proveedor revocó el acceso (cambió la contraseña del buzón, un admin quitó la aplicación o venció el consentimiento). El canal deja de revisarse hasta que haces clic en reconectar e inicias sesión otra vez como el buzón. No se pierde nada: el correo no leído se toma al reconectar.
• Microsoft o Google dicen que la URI de redirección no coincide: la URI registrada en tu aplicación tiene que ser exactamente <WEB_ORIGIN>/api/email-channels/oauth/callback (o <API_PUBLIC_URL>/email-channels/oauth/callback si esa está definida). Ver Conectar Microsoft 365 o Gmail.
• Buzones con contraseña después de cambiar ENCRYPTION_KEY: todo secreto guardado con la clave anterior queda ilegible. Vuelve a cargar la contraseña (o reconecta un canal OAuth) desde Canales de correo.

Fuera de eso, revisa los logs de worker: es quien revisa los buzones, no api.

Alguien perdió su app autenticadora

Puede entrar con uno de sus códigos de recuperación en lugar del código de 6 dígitos. Cada uno sirve una sola vez.

Si ya no le quedan códigos, otro administrador le restablece la verificación en dos pasos desde Ajustes → Usuarios (restablecer 2FA). La vuelve a configurar en su próximo inicio de sesión si el espacio de trabajo la exige.

Si la persona bloqueada es la única administradora, nadie puede restablecerla desde la consola. Hazlo directamente en la base de datos (cambia el slug y el correo):

docker compose -f infra/docker-compose.yml exec postgres psql -U app_migrator seredina -c "
  UPDATE users SET mfa_secret_encrypted = NULL, mfa_pending_secret_encrypted = NULL,
    mfa_enabled_at = NULL, mfa_last_used_step = NULL, mfa_recovery_code_hashes = '{}',
    failed_login_attempts = 0, locked_until = NULL
  WHERE email = 'admin@ejemplo.com'
    AND tenant_id = (SELECT id FROM tenants WHERE slug = 'tu-organizacion');"

Un cambio hecho así no queda en el registro de auditoría. Después crea un segundo administrador para no tener que volver a hacerlo.

El inicio de sesión único no funciona

• El proveedor muestra un error antes de volver: la URI de redirección registrada en el proveedor tiene que coincidir exactamente con la que muestra Ajustes → Inicio de sesión único.
• "Accounts from example.com can't sign in to this workspace" (los errores del SSO llegan en inglés): ese dominio no está en la lista de dominios permitidos. Agrégalo o vacía la lista.
• "There's no account for … in this workspace": la creación automática de cuentas está apagada. Crea el usuario antes, o actívala y elige el rol que reciben los usuarios nuevos.
• Bloqueado por "exigir SSO" mientras el proveedor está caído: los administradores siempre pueden entrar con su contraseña. Desactiva "exigir SSO" hasta que el proveedor vuelva.

No llegan los enlaces del portal, las invitaciones o los restablecimientos de contraseña

Estos correos salen por tus canales de correo, así que al menos uno tiene que estar conectado (revisa los errores en Canales de correo). Las invitaciones no se envían sin uno; un restablecimiento o un enlace del portal simplemente no puede salir. Para los enlaces del portal y de restablecimiento, cada dirección recibe como máximo 3 por hora, y la página responde lo mismo conozca o no la dirección, así que un error de tipeo parece un éxito. Un envío que falla queda en los logs de worker. Los enlaces apuntan a WEB_ORIGIN, que tiene que ser la dirección a la que llegan las personas.

Puerto ya en uso

API_PORT (4000), WEB_PORT (8080), POSTGRES_PORT (5432) y REDIS_PORT (6379) son los cuatro puertos expuestos al host. Si alguno choca con otro servicio ya corriendo en tu máquina, cámbialo en .env — no hace falta tocar nada más, el docker-compose.yml los lee todos como variables.

docker compose no se reconoce

Necesitas el plugin moderno (docker compose, sin guion), no el binario viejo docker-compose v1 (con guion) — son paquetes distintos. En Ubuntu/Debian, sudo apt install docker-compose-plugin lo instala; en Docker Desktop ya viene incluido.

Nada de esto resuelve tu caso

Abre un issue en GitHub con la salida de docker compose logs del servicio que falla y tu .env sin los valores de los secretos (nombres de variable sí, valores no).