Skip to content

setup.md

Latest commit

 

History

History
104 lines (76 loc) · 3 KB

setup.md

File metadata and controls

104 lines (76 loc) · 3 KB

Setup

Pré-requisitos

  • Bun >= 1.0
  • Docker + Docker Compose
  • Chave de API de pelo menos um provedor LLM (OpenRouter, Gemini ou Anthropic)

Instalação

# Clonar repositório
git clone <repo-url> && cd study-rag

# Instalar dependências
bun install

Configuração de Ambiente

cp api/.env.example api/.env

Editar api/.env:

Variável Descrição Obrigatória
PORT Porta da API Não (default: 3000)
QDRANT_URL URL do Qdrant Não (default: http://localhost:6333)
NEO4J_URI URI do Neo4j Não (default: bolt://localhost:7687)
NEO4J_USER Usuário Neo4j Não (default: neo4j)
NEO4J_PASSWORD Senha Neo4j Não (default: password123)
OLLAMA_URL URL do Ollama Não (default: http://localhost:11434)
OLLAMA_EMBEDDING_MODEL Modelo de embedding Não (default: jina/jina-embeddings-v2-base-code)
GEMINI_API_KEY API key Google Gemini Condicional*
OPENROUTER_API_KEY API key OpenRouter Condicional*

*Pelo menos uma chave de LLM é necessária. Configuração feita via UI em Settings.

Desenvolvimento Local

macOS (Ollama nativo — recomendado)

No macOS, Ollama roda nativamente com acesso direto ao Metal (GPU Apple Silicon), muito mais rápido que containerizado.

# 1. Instalar e iniciar Ollama nativamente
brew install ollama
ollama serve &
ollama pull unclemusclez/jina-embeddings-v2-base-code

# 2. Subir infraestrutura (sem Ollama)
docker compose up -d

# 3. API (hot reload)
cd api && bun run dev

# 4. Frontend (outro terminal)
cd web && bun run dev

Linux/Windows (Ollama containerizado)

# 1. Subir infraestrutura + Ollama no Docker
docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d

# 2. API (hot reload)
cd api && bun run dev

# 3. Frontend (outro terminal)
cd web && bun run dev

Produção (Docker Compose)

# macOS (Ollama nativo)
docker compose up -d --build

# Linux/Windows (Ollama no container)
docker compose -f docker-compose.yml -f docker-compose.ollama.yml up -d --build

Troubleshooting

Problema Solução
Ollama não responde (container) Aguardar ollama-setup terminar pull do modelo (~2GB)
Ollama não responde (nativo) Verificar se ollama serve está rodando
Erro de embedding Verificar se modelo está disponível: curl http://localhost:11434/api/tags
Frontend não conecta na API Verificar se API está rodando na porta 3000
Qdrant connection refused docker compose up -d qdrant e aguardar inicialização
API não conecta no Ollama nativo (Docker) Verificar que OLLAMA_URL usa host.docker.internal:11434