Saltar al contenido principal

Documentation Index

Fetch the complete documentation index at: https://docs.kodus.io/llms.txt

Use this file to discover all available pages before exploring further.

Esta guía es para propósitos de desarrollo local. Para el despliegue en producción, consulta la guía Desplegar Kodus.
El dev local se ejecuta con API_CLOUD_MODE=false, el mismo modo que una instancia self-hosted — lo que significa que el heartbeat anónimo diario a telemetry.kodus.io está habilitado por defecto. Si no quieres que tus experimentos locales aparezcan en la flota, define KODUS_TELEMETRY_DISABLED=true en tu .env. Consulta Telemetría Anónima para ver qué se envía y cómo inspeccionarlo.

​
Requisitos previos

  • Node.js (versión LTS)
  • Docker
  • Yarn o NPM
  • Claves de API de LLM

​
Ejecutar el proyecto

Para una configuración rápida y automatizada, utiliza nuestro script de configuración:
git clone https://github.com/kodustech/kodus-ai.git
cd kodus-ai
yarn setup
Este script realizará automáticamente:
  • ✅ Verificar todas las dependencias requeridas (Node.js, Yarn, Docker, OpenSSL)
  • ✅ Instalar las dependencias del proyecto
  • ✅ Crear y configurar el archivo .env
  • ✅ Generar todas las claves de seguridad requeridas automáticamente
  • ✅ Configurar las redes de Docker
  • ✅ Proporcionar los próximos pasos de forma clara

​
Elige tu modo LLM (obligatorio)

Selecciona un modo y completa tu .env antes de iniciar los servicios.

​
Próximos pasos

Configuración básica:
yarn docker:start
yarn migrate:dev
yarn seed
Con integraciones externas (webhooks, etc.):
yarn docker:start
yarn migrate:dev
yarn seed
yarn tunnel  # Crea un endpoint público para servicios externos
Una vez que todo esté en funcionamiento, abre http://localhost:3000 en tu navegador.

​
Flujo de trabajo de desarrollo

​
Desarrollo local básico

  1. Iniciar servicios: yarn docker:start
  2. Ejecutar migraciones: yarn migrate:dev
  3. Cargar datos iniciales: yarn seed
  4. Abrir la aplicación: Visita http://localhost:3000
  5. Verificación de salud: yarn dev:health-check

​
Desarrollo con integraciones externas

Si necesitas probar integraciones con servicios externos (como webhooks de Git):
  1. Iniciar servicios: yarn docker:start && yarn migrate:dev && yarn seed
  2. Crear túnel: yarn tunnel (crea un endpoint público)
  3. Actualizar URLs de webhook: El comando tunnel actualiza tu .env automáticamente
  4. Configurar el proveedor Git: Usa la URL del túnel en la configuración de webhooks de tu proveedor Git
  5. Probar la integración: Dispara webhooks y monitorea los logs
Ventajas del túnel:
  • Probar integraciones de webhook reales localmente
  • Depurar comunicaciones con servicios externos
  • Compartir tu entorno de desarrollo con compañeros de equipo
  • Probar aplicaciones móviles u otros clientes externos

​
Solución de problemas

​
Verificación rápida de salud

yarn dev:health-check
Esta verificación de salud exhaustiva valida:
  • ✅ Servicios: Kodus API, Worker, Webhooks, Web, PostgreSQL, MongoDB, RabbitMQ
  • 🔌 Disponibilidad de puertos: Web (3000), API (3001), PostgreSQL (5432), MongoDB (27017), RabbitMQ (5672/15672)
  • 🗄️ Configuración de base de datos: Migraciones y datos iniciales
  • 🌐 Endpoints de API: Endpoints de salud y conectividad básica

​
Verificación manual

  1. Verificar la interfaz web: Visita http://localhost:3000 en tu navegador
  2. Verificar la salud de la API: Visita http://localhost:3001/health
  3. Verificar RabbitMQ: Visita http://localhost:15672 (credenciales por defecto: guest/guest)
  4. Verificar las conexiones de base de datos: Revisa los logs para confirmar conexiones exitosas a la base de datos
  5. Probar los endpoints de webhook: Los webhooks de tu proveedor Git deben apuntar a http://localhost:3332/[proveedor]/webhook (o al dominio de tu API si un proxy inverso enruta /.../webhook al servicio de webhooks)

​
Problemas con el script de configuración

Si el script de configuración automatizada (yarn setup) falla: Dependencias faltantes: 
# Verificar si todas las herramientas requeridas están instaladas
node --version
yarn --version
docker --version
openssl version
Problemas de permisos con Docker: 
# Agregar tu usuario al grupo docker (Linux/macOS)
sudo usermod -aG docker $USER
# Luego cierra sesión y vuelve a iniciarla
Errores al crear redes: 
# Verificar si las redes ya existen
docker network ls | grep kodus
# Eliminar redes conflictivas si es necesario
docker network rm kodus-backend-services shared-network

​
Problemas comunes

Conflictos de puertos:
  • Asegúrate de que los puertos 3000 (Web), 3001 (API), 5432 (PostgreSQL), 27017 (MongoDB) y 5672/15672 (RabbitMQ) estén disponibles
  • Detén otros servicios que usen estos puertos antes de iniciar Kodus
Variables de entorno no se cargan:
  • Verifica que tu archivo .env exista en la raíz del proyecto
  • Comprueba que no haya espacios al final en las asignaciones de variables
  • Asegúrate de que todas las claves de seguridad requeridas se hayan generado correctamente
Fallos en la verificación de salud:
  • Ejecuta yarn dev:health-check para obtener diagnósticos detallados
  • Comprueba si los contenedores están completamente iniciados (espera 1-2 minutos después de yarn docker:start)
  • Verifica que las migraciones de base de datos y los datos iniciales estén cargados
  • Revisa los logs de la API con yarn docker:logs para ver errores de inicio
La API no responde:
  • La API tarda un tiempo en inicializarse completamente después de que el contenedor arranca
  • Verifica si las migraciones y los datos iniciales están cargados
  • Comprueba que el archivo .env tenga todas las variables requeridas
  • Ejecuta la verificación de salud para ver qué componentes específicos están fallando
Problemas de webhooks con servicios externos:
  • Usa yarn tunnel para crear un endpoint público para webhooks externos
  • Actualiza las URLs de webhook de tu proveedor Git para usar la URL del túnel
  • Asegúrate de que el túnel esté activo cuando pruebes integraciones de webhook
  • Revisa los logs del túnel para detectar problemas de conexión