Início Rápido Local

Este guia é destinado ao desenvolvimento local. Para implantação em produção, consulte o guia Implantar Kodus.

Pré-requisitos

Node.js (versão LTS)
Docker
Yarn ou NPM
Chaves de API de LLM

Executando o projeto

Configuração Automatizada (Recomendada)
Configuração Manual

Para uma configuração rápida e automatizada, use nosso script de setup:

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

Este script irá automaticamente:

✅ Verificar todas as dependências necessárias (Node.js, Yarn, Docker, OpenSSL)
✅ Instalar as dependências do projeto
✅ Criar e configurar o arquivo .env
✅ Gerar automaticamente todas as chaves de segurança necessárias
✅ Configurar as redes Docker
✅ Fornecer os próximos passos de forma clara

Escolha seu modo de LLM (obrigatório)

Selecione um modo e preencha seu .env antes de iniciar os serviços.

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 passos

Configuração básica:

yarn docker:start
yarn migrate:dev
yarn seed

Com integrações externas (webhooks, etc.):

yarn docker:start
yarn migrate:dev
yarn seed
yarn tunnel  # Cria endpoint público para serviços externos

Após tudo estar em execução, abra http://localhost:3000 no seu navegador.

Se preferir configurar tudo manualmente:

1. Clonar o repositório

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

2. Instalar dependências

yarn install

3. Configurar variáveis de ambiente

cp .env.example .env

4. Escolha seu modo de LLM (obrigatório)

Selecione um modo e preencha seu .env antes de iniciar os serviços.

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. Gerar Chaves de Segurança

Antes de configurar suas variáveis de ambiente, você precisará gerar chaves seguras para tokens JWT e outras configurações relacionadas à segurança:

# Para a maioria das chaves de segurança (segredos JWT, etc.)
openssl rand -base64 32

# Para chaves de criptografia e segredos de gerenciamento de código
openssl rand -hex 32

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

Você precisará gerar valores para estas chaves de segurança:

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

6. Configurar redes Docker

Crie as redes Docker necessárias:

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

7. Iniciar o ambiente de desenvolvimento

Inicie os serviços usando Docker:

yarn docker:start

Este comando inicia:

Kodus API
Worker (tarefas assíncronas)
Serviço de Webhooks
Aplicação Web do Kodus
Banco de dados PostgreSQL
Banco de dados MongoDB
RabbitMQ
Configurações de rede necessárias

Para também criar um endpoint público para serviços externos:

yarn tunnel

8. Configuração inicial

Se for a primeira vez que executa o projeto, execute os seguintes comandos:Executar migrações do banco de dados:

yarn migrate:dev

Carregar dados iniciais:

yarn seed

9. Endpoints dos serviços

Acesse os serviços em:

Web UI: http://localhost:3000
API: http://localhost:3001
Gerenciamento RabbitMQ: http://localhost:15672
Porta de Debug: 9229

Fluxo de desenvolvimento

Desenvolvimento Local Básico

Iniciar serviços: yarn docker:start
Executar migrações: yarn migrate:dev
Carregar dados iniciais: yarn seed
Abrir o app: Acesse http://localhost:3000
Verificação de saúde: yarn dev:health-check

Desenvolvimento com Integrações Externas

Se precisar testar integrações com serviços externos (como webhooks Git):

Iniciar serviços: yarn docker:start && yarn migrate:dev && yarn seed
Criar tunnel: yarn tunnel (cria endpoint público)
Atualizar URLs de webhook: O comando tunnel atualiza seu .env automaticamente
Configurar provedor Git: Use a URL do tunnel nas configurações de webhook do seu provedor Git
Testar integração: Dispare webhooks e monitore os logs

Benefícios do Tunnel:

Testar integrações reais de webhook localmente
Depurar comunicações com serviços externos
Compartilhar seu ambiente de desenvolvimento com membros da equipe
Testar aplicativos móveis ou outros clientes externos

Solução de Problemas

Verificação Rápida de Saúde

yarn dev:health-check

Esta verificação abrangente de saúde valida:

✅ Serviços: Kodus API, Worker, Webhooks, Web, PostgreSQL, MongoDB, RabbitMQ
🔌 Disponibilidade de portas: Web (3000), API (3001), PostgreSQL (5432), MongoDB (27017), RabbitMQ (5672/15672)
🗄️ Configuração do banco de dados: Migrações e dados iniciais
🌐 Endpoints da API: Endpoints de saúde e conectividade básica

Verificação Manual

Verificar Web UI: Acesse http://localhost:3000 no seu navegador
Verificar saúde da API: Acesse http://localhost:3001/health
Verificar RabbitMQ: Acesse http://localhost:15672 (credenciais padrão: guest/guest)
Verificar conexões com banco de dados: Verifique os logs para conexões bem-sucedidas
Testar endpoints de webhook: Os webhooks do seu provedor Git devem apontar para http://localhost:3332/[provider]/webhook (ou para o domínio da sua API se um proxy reverso rotear /.../webhook para o serviço de webhooks)

Problemas com o Script de Setup

Se o script de configuração automatizada (yarn setup) falhar: Dependências ausentes:

# Verificar se todas as ferramentas necessárias estão instaladas
node --version
yarn --version
docker --version
openssl version

Problemas de permissão com Docker:

# Adicionar seu usuário ao grupo docker (Linux/macOS)
sudo usermod -aG docker $USER
# Depois saia e entre novamente na sessão

Erros na criação de redes:

# Verificar se as redes já existem
docker network ls | grep kodus
# Remover redes conflitantes se necessário
docker network rm kodus-backend-services shared-network

Problemas Comuns

Conflitos de porta:

Certifique-se de que as portas 3000 (Web), 3001 (API), 5432 (PostgreSQL), 27017 (MongoDB) e 5672/15672 (RabbitMQ) estão disponíveis
Pare outros serviços que usam essas portas antes de iniciar o Kodus

Variáveis de ambiente não carregando:

Verifique se o arquivo .env existe na raiz do projeto
Confira se não há espaços no final das atribuições de variáveis
Certifique-se de que todas as chaves de segurança necessárias foram geradas corretamente

Falhas na verificação de saúde:

Execute yarn dev:health-check para obter diagnósticos detalhados
Verifique se os contêineres estão totalmente iniciados (aguarde 1-2 minutos após yarn docker:start)
Confirme que as migrações e dados iniciais foram carregados
Verifique os logs da API com yarn docker:logs para erros de inicialização

API sem resposta:

A API leva algum tempo para inicializar completamente após a inicialização do contêiner
Verifique se as migrações e dados iniciais foram carregados
Confirme que o arquivo .env possui todas as variáveis necessárias
Execute a verificação de saúde para ver quais componentes específicos estão falhando

Problemas de webhook com serviços externos:

Use yarn tunnel para criar um endpoint público para webhooks externos
Atualize as URLs de webhook do seu provedor Git para usar a URL do tunnel
Certifique-se de que o tunnel está em execução ao testar integrações de webhook
Verifique os logs do tunnel para problemas de conexão

Conceitos

Início Rápido Local

Implantar com Docker

Configuração de Provedores Git

Início Rápido Local

Pré-requisitos

Executando o projeto

Escolha seu modo de LLM (obrigatório)

Model Configuration Guides

Próximos passos

1. Clonar o repositório

2. Instalar dependências

3. Configurar variáveis de ambiente

4. Escolha seu modo de LLM (obrigatório)

Model Configuration Guides

5. Gerar Chaves de Segurança

6. Configurar redes Docker

7. Iniciar o ambiente de desenvolvimento

8. Configuração inicial

9. Endpoints dos serviços

Fluxo de desenvolvimento

Desenvolvimento Local Básico

Desenvolvimento com Integrações Externas

Solução de Problemas

Verificação Rápida de Saúde

Verificação Manual

Problemas com o Script de Setup

Problemas Comuns

Conceitos

Início Rápido Local

Implantar com Docker

Configuração de Provedores Git

​Pré-requisitos

​Executando o projeto

​Escolha seu modo de LLM (obrigatório)

Model Configuration Guides

​Próximos passos

​1. Clonar o repositório

​2. Instalar dependências

​3. Configurar variáveis de ambiente

​4. Escolha seu modo de LLM (obrigatório)

Model Configuration Guides

​5. Gerar Chaves de Segurança

​6. Configurar redes Docker

​7. Iniciar o ambiente de desenvolvimento

​8. Configuração inicial

​9. Endpoints dos serviços

​Fluxo de desenvolvimento

​Desenvolvimento Local Básico

​Desenvolvimento com Integrações Externas

​Solução de Problemas

​Verificação Rápida de Saúde

​Verificação Manual

​Problemas com o Script de Setup

​Problemas Comuns

Pré-requisitos

Executando o projeto

Escolha seu modo de LLM (obrigatório)

Próximos passos

1. Clonar o repositório

2. Instalar dependências

3. Configurar variáveis de ambiente

4. Escolha seu modo de LLM (obrigatório)

5. Gerar Chaves de Segurança

6. Configurar redes Docker

7. Iniciar o ambiente de desenvolvimento

8. Configuração inicial

9. Endpoints dos serviços

Fluxo de desenvolvimento

Desenvolvimento Local Básico

Desenvolvimento com Integrações Externas

Solução de Problemas

Verificação Rápida de Saúde

Verificação Manual

Problemas com o Script de Setup

Problemas Comuns