Saltar a contenido

🚀 Local Setup Guide - Aeternus

Guía completa para ejecutar todo el proyecto localmente. Esta guía es para desarrolladores juniors — siéntete libre de pedir ayuda si algo no funciona.

📋 Tabla de contenidos

  1. Requisitos previos
  2. Setup inicial del proyecto
  3. Configurar variables de entorno
  4. Ejecutar el backend (Core)
  5. Ejecutar el frontend (Next.js)
  6. Verificar que todo funciona
  7. Troubleshooting
  8. Próximos pasos

Requisitos previos

Instala esto antes de empezar:

Node.js (para el frontend)

  • Versión requerida: 20.x - 21.x
  • Descargar desde: https://nodejs.org/

Python (para el backend)

  • Versión requerida: 3.9+
  • Descargar desde: https://www.python.org/

PostgreSQL (base de datos)

  • Versión requerida: 13+
  • Descargar desde: https://www.postgresql.org/download/

Git

  • Descargar desde: https://git-scm.com/

Setup inicial

1. Clonar el repositorio

git clone https://github.com/your-org/aeternus.git
cd aeternus

2. Instalar dependencias del frontend

npm install

3. Configurar el backend

cd core
make setup
cd ..

Variables de entorno

Copiar archivos .env.example

cp .env.example .env.local
cd core && cp .env.example .env && cd ..

Configurar variables del frontend

Abre .env.local en la raíz:

NEXT_PUBLIC_BASE_URL=http://localhost:3000
NEXT_PUBLIC_CORE_API_BASE_URL=http://localhost:8080
DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aeternus

# Opcionales:
AUTH0_SECRET=your-secret-key
AUTH0_BASE_URL=http://localhost:3000
AUTH0_ISSUER_BASE_URL=https://YOUR_AUTH0_DOMAIN.auth0.com
AUTH0_CLIENT_ID=your-client-id
AUTH0_CLIENT_SECRET=your-client-secret

OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o

NEO4J_URI=neo4j+s://your-uri.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_OFFLINE=true

ELEVENLABS_API_KEY=your-key
ELEVENLABS_VOICE_ID=your-voice-id
ELEVENLABS_MODEL_ID=eleven_multilingual_v2

SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=your-email@example.com
SMTP_PASSWORD=your-password
SMTP_FROM_EMAIL=noreply@aeternus.ai

Configurar variables del backend

Abre core/.env:

CORE_MOCK_MODE=true

# Si quieres respuestas reales:
OPENAI_API_KEY=sk-your-key-here
OPENAI_MODEL=gpt-4o
CORE_MOCK_MODE=false

DATABASE_URL=postgresql://postgres:postgres@localhost:5432/aeternus

NEO4J_URI=neo4j+s://your-uri.databases.neo4j.io
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password
NEO4J_OFFLINE=true

CORS_ORIGINS=http://localhost:3000,http://localhost:3001
APP_ENV=development

Crear la base de datos

psql -U postgres -c "CREATE DATABASE aeternus;"

O con Docker:

docker run --name aeternus-postgres \
  -e POSTGRES_PASSWORD=postgres \
  -e POSTGRES_DB=aeternus \
  -p 5432:5432 \
  -d postgres:15

Ejecutar el backend

Terminal 1: Backend

cd core
source .venv/bin/activate  # Windows: .venv\Scripts\activate
make run

Debería mostrar:

Uvicorn running on http://127.0.0.1:8080

Probar que funciona:

curl http://localhost:8080/v1/health

Ejecutar el frontend

Terminal 2: Frontend

npm run dev

Abre http://localhost:3000 en tu navegador. ✅

Verificar que todo funciona

1. Frontend

2. Backend

  • Terminal con make run muestra Uvicorn running on...

3. Conexión

  • F12 en el navegador
  • Network tab → intenta chatear
  • Deberías ver requests a http://localhost:8080/v1/chat

Troubleshooting

"Port 3000 already in use"

npm run dev:clean

"Port 8080 already in use"

make stop

"ModuleNotFoundError" en Python

cd core
source .venv/bin/activate
pip install -r requirements.txt
make run

"database 'aeternus' does not exist"

psql -U postgres -c "CREATE DATABASE aeternus;"

Node version mismatch

node --version  # Debe ser v20.x o v21.x

# macOS/Linux:
nvm install 20 && nvm use 20

# Windows: Descarga desde nodejs.org

Próximos pasos

  1. Explora el código en src/app/page.tsx y core/app/routes/
  2. Lee la Project Structure Guide
  3. Lee la Contributing Guide

¿Necesitas ayuda? Pregunta sin problema. 🚀