Inicio rápido local

Esta guía es para propósitos de desarrollo local. Para el despliegue en producción, consulta la guía Desplegar Kodus.

Requisitos previos

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

Ejecutar el proyecto

Configuración automatizada (recomendada)
Configuración manual

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.

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

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.

Si prefieres configurar todo manualmente:

1. Clonar el repositorio

git clone https://github.com/kodustech/kodus-ai.git

2. Instalar dependencias

yarn install

3. Configurar las variables de entorno

cp .env.example .env

4. Elige tu modo LLM (obligatorio)

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

Fixed Mode (Recommended for Self-Hosted)
Automatic Mode (High Quality)

This is the simplest mode and recommended for self-hosted installations. You only need to configure a single LLM model.

# Fixed Mode Configuration
API_LLM_PROVIDER_MODEL="gpt-3.5-turbo"     # Model you want to use
API_OPENAI_FORCE_BASE_URL="https://your-api.com/v1"  # Your API provider URL
API_OPEN_AI_API_KEY="your-api-key"          # Your API provider key

This mode is ideal for self-hosted because:

Requires only a single API key
Works with any OpenAI-compatible API provider
Easier to configure and maintain

Model Configuration Guides

Check our model-specific guides for detailed setup instructions with popular providers like Novita, OpenAI, Anthropic, and more.

This mode uses multiple LLM models to achieve the best possible results. Requires more configuration but offers the highest quality analysis.

# Automatic Mode Configuration
API_OPEN_AI_API_KEY=                       # OpenAI API key
API_GOOGLE_AI_API_KEY=                     # Google AI API key
API_ANTHROPIC_API_KEY=                     # Anthropic API key
API_NOVITA_AI_API_KEY=                     # Novita AI API key
API_VERTEX_AI_API_KEY=                     # Vertex AI API key

This mode offers the best quality because:

Uses multiple specialized models
Our pipeline is optimized to extract the best from each model
Ideal for enterprise installations prioritizing quality

5. Generar claves de seguridad

Antes de configurar las variables de entorno, necesitarás generar claves seguras para los tokens JWT y otras configuraciones relacionadas con la seguridad:

# Para la mayoría de las claves de seguridad (secretos JWT, etc.)
openssl rand -base64 32

# Para claves criptográficas y secretos de gestión de código
openssl rand -hex 32

# Para tokens de webhook (seguros para URL)
openssl rand -base64 32 | tr -d '=' | tr '/+' '_-'

Necesitarás generar valores para estas claves de seguridad:

JWT_SECRET (usar openssl rand -base64 32)
JWT_REFRESH_SECRET (usar openssl rand -base64 32)
CODE_MANAGEMENT_SECRET (usar openssl rand -hex 32)
CODE_MANAGEMENT_WEBHOOK_TOKEN (usar openssl rand -base64 32 | tr -d '=' | tr '/+' '_-')

6. Configurar las redes de Docker

Crea las redes de Docker requeridas:

docker network create kodus-backend-services || true
docker network create shared-network || true

7. Iniciar el entorno de desarrollo

Lanza los servicios usando Docker:

yarn docker:start

Este comando inicia:

Kodus API
Worker (trabajos asíncronos)
Servicio de Webhooks
Aplicación Web de Kodus
Base de datos PostgreSQL
Base de datos MongoDB
RabbitMQ
Configuraciones de red requeridas

Para crear también un endpoint público para servicios externos:

yarn tunnel

8. Configuración inicial

Si es la primera vez que ejecutas el proyecto, ejecuta los siguientes comandos:Ejecutar migraciones de base de datos:

yarn migrate:dev

Cargar datos iniciales:

yarn seed

9. Endpoints de los servicios

Accede a los servicios en:

Interfaz web: http://localhost:3000
API: http://localhost:3001
Gestión de RabbitMQ: http://localhost:15672
Puerto de depuración: 9229

Flujo de trabajo de desarrollo

Desarrollo local básico

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

Desarrollo con integraciones externas

Si necesitas probar integraciones con servicios externos (como webhooks de Git):

Iniciar servicios: yarn docker:start && yarn migrate:dev && yarn seed
Crear túnel: yarn tunnel (crea un endpoint público)
Actualizar URLs de webhook: El comando tunnel actualiza tu .env automáticamente
Configurar el proveedor Git: Usa la URL del túnel en la configuración de webhooks de tu proveedor Git
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

Verificar la interfaz web: Visita http://localhost:3000 en tu navegador
Verificar la salud de la API: Visita http://localhost:3001/health
Verificar RabbitMQ: Visita http://localhost:15672 (credenciales por defecto: guest/guest)
Verificar las conexiones de base de datos: Revisa los logs para confirmar conexiones exitosas a la base de datos
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

Conceptos

Inicio Rápido Local

Despliegue con Docker

Configuración de Proveedores Git

Inicio rápido local

Requisitos previos

Ejecutar el proyecto

Elige tu modo LLM (obligatorio)

Model Configuration Guides

Próximos pasos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar las variables de entorno

4. Elige tu modo LLM (obligatorio)

Model Configuration Guides

5. Generar claves de seguridad

6. Configurar las redes de Docker

7. Iniciar el entorno de desarrollo

8. Configuración inicial

9. Endpoints de los servicios

Flujo de trabajo de desarrollo

Desarrollo local básico

Desarrollo con integraciones externas

Solución de problemas

Verificación rápida de salud

Verificación manual

Problemas con el script de configuración

Problemas comunes

Conceptos

Inicio Rápido Local

Despliegue con Docker

Configuración de Proveedores Git

​Requisitos previos

​Ejecutar el proyecto

​Elige tu modo LLM (obligatorio)

Model Configuration Guides

​Próximos pasos

​1. Clonar el repositorio

​2. Instalar dependencias

​3. Configurar las variables de entorno

​4. Elige tu modo LLM (obligatorio)

Model Configuration Guides

​5. Generar claves de seguridad

​6. Configurar las redes de Docker

​7. Iniciar el entorno de desarrollo

​8. Configuración inicial

​9. Endpoints de los servicios

​Flujo de trabajo de desarrollo

​Desarrollo local básico

​Desarrollo con integraciones externas

​Solución de problemas

​Verificación rápida de salud

​Verificación manual

​Problemas con el script de configuración

​Problemas comunes

Requisitos previos

Ejecutar el proyecto

Elige tu modo LLM (obligatorio)

Próximos pasos

1. Clonar el repositorio

2. Instalar dependencias

3. Configurar las variables de entorno

4. Elige tu modo LLM (obligatorio)

5. Generar claves de seguridad

6. Configurar las redes de Docker

7. Iniciar el entorno de desarrollo

8. Configuración inicial

9. Endpoints de los servicios

Flujo de trabajo de desarrollo

Desarrollo local básico

Desarrollo con integraciones externas

Solución de problemas

Verificación rápida de salud

Verificación manual

Problemas con el script de configuración

Problemas comunes