Saltearse al contenido
Documentación de la Plataforma Algesta

Configuración de Desarrollo Local

Tabla de Contenidos

Propósito

Esta guía permite a los desarrolladores configurar la plataforma Algesta completa localmente para desarrollo, pruebas y depuración. Proporciona instrucciones paso a paso verificables para tener todos los microservicios y el dashboard ejecutándose en una máquina local en 1 hora.

Siguiendo esta guía, podrás:

  • Clonar y configurar todos los repositorios de Algesta
  • Instalar dependencias y configurar variables de entorno
  • Ejecutar servicios individualmente o vía Docker Compose
  • Verificar que todos los servicios se ejecutan correctamente con health checks
  • Comenzar trabajo de desarrollo con un stack local completamente funcional

¿Para quién es esto?

Principalmente para desarrolladores en proceso de onboarding e ingenieros que se unen al proyecto Algesta. También útil para ingenieros DevOps probando entornos locales o solucionando problemas de despliegue.

Prerrequisitos

Antes de comenzar, asegúrate de tener lo siguiente instalado en tu máquina de desarrollo:

HerramientaVersión RequeridaInstalaciónComando de Verificación
Node.js20.x o 21.xnodejs.orgnode --version
npm10.x+Incluido con Node.jsnpm --version
pnpm10.x+ (para dashboard)npm install -g pnpmpnpm --version
MongoDB7.x+mongodb.commongod --version
Docker24.x+docker.comdocker --version
Docker Compose2.x+Incluido con Docker Desktopdocker-compose --version
Git2.x+git-scm.comgit --version

Opcional pero Recomendado:

  • Redis 7.x+ para caché y mensajería (se puede usar Docker)
  • Kafka para mensajería event-driven (se puede usar Docker)
  • Azure CLI para integración con almacenamiento en la nube
  • Postman o curl para pruebas de API

Descripción General de Repositorios

La plataforma Algesta consiste de 7 repositorios principales organizados en una estructura multi-repo:

RepositorioPropósitoStack TecnológicoPuerto
algesta-ms-orders-nestjsGestión del ciclo de vida de órdenes, cotizaciones, seguimiento de activosNestJS, MongoDB, Redis, Kafka3001
algesta-ms-notifications-nestjsDespacho de notificaciones (email, in-app)NestJS, MongoDB, SendGrid3002
algesta-ms-provider-nestjsRegistro de proveedores, subastas, validación de documentosNestJS, MongoDB, Azure Storage3003
algesta-api-gateway-nestjsAPI Gateway con limitación de tasa, enrutamiento, autenticaciónNestJS, Redis3000
algesta-dashboard-reactSPA de dashboard para admin y clienteReact 19, Vite, TanStack Query5173
algesta-agent(Futuro) Agente de IA conversacionalPython, LangChainTBD
ops-algestaInfraestructura como Código (Terraform, configs)Terraform, YAMLN/A

Directorio Base: Todos los repos deben clonarse en tu directorio de proyecto preferido.

Configuración del Entorno de Desarrollo

1. Crear Directorio del Proyecto

Ventana de terminal
mkdir -p ~/Documents/3A/Algesta
cd ~/Documents/3A/Algesta

Verificación: Ejecuta pwd y confirma que estás en el directorio Algesta.

2. Instalar Dependencias Globales

Ventana de terminal
# Instalar pnpm globalmente (para el dashboard)
npm install -g pnpm


# Instalar Husky globalmente (opcional, para git hooks)
npm install -g husky


# Instalar NestJS CLI (opcional, útil para generar código)
npm install -g @nestjs/cli

Verificación:

Ventana de terminal
pnpm --version
# Salida esperada: 10.15.0 o superior


nest --version
# Salida esperada: 11.0.0 o superior

3. Iniciar MongoDB Localmente

Opción A: MongoDB Nativo

Ventana de terminal
# macOS con Homebrew
brew services start mongodb-community@7


# Linux
sudo systemctl start mongod

Opción B: MongoDB con Docker

Ventana de terminal
docker run -d \
  --name algesta-mongo \
  -p 27017:27017 \
  -v algesta-mongo-data:/data/db \
  mongo:7

Verificación:

Ventana de terminal
mongosh --eval "db.version()"
# Salida esperada: 7.x.x

Si la conexión a MongoDB falla, consulta la Guía de Solución de Problemas.

Configuración Servicio por Servicio

Microservicio de Órdenes

1. Clonar Repositorio

Ventana de terminal
cd ~/Documents/3A/Algesta
git clone <REPOSITORY_URL> algesta-ms-orders-nestjs
cd algesta-ms-orders-nestjs

2. Instalar Dependencias

Ventana de terminal
npm install --force

Nota: La bandera --force se usa para manejar dependencias nativas de bcrypt y descargas de Puppeteer.

3. Configurar Entorno

Crear archivo .env en el directorio raíz:

Ventana de terminal
cp .env.example .env

Editar .env con las variables mínimas requeridas (ver Configuración de Entorno para detalles completos):

NODE_ENV=development
PORT=3001
MONGODB_URI=mongodb://localhost:27017/orders_ms
JWT_SECRET=your-dev-jwt-secret-min-32-chars
REDIS_HOST=localhost
REDIS_PORT=6379

4. Ejecutar en Modo Desarrollo

Ventana de terminal
npm run start:dev

Verificación:

Ventana de terminal
curl http://localhost:3001/health
# Salida esperada: {"status":"ok","timestamp":"2025-11-20T..."}

5. Ejecutar Pruebas

Ventana de terminal
npm run test:cov

Esperado: Cobertura > 90% (objetivo actual).

Microservicio de Notificaciones

1. Clonar e Instalar

Ventana de terminal
cd ~/Documents/3A/Algesta
git clone <REPOSITORY_URL> algesta-ms-notifications-nestjs
cd algesta-ms-notifications-nestjs
npm install --force

2. Configurar Entorno

NODE_ENV=development
PORT=3002
MONGODB_URI=mongodb://localhost:27017/notifications_ms
SENDGRID_API_KEY=your-sendgrid-api-key
EMAIL_FROM=noreply@algesta.com
REDIS_HOST=localhost
REDIS_PORT=6379

Nota: Para desarrollo local, puedes usar una clave API de sandbox de SendGrid u omitir el envío de correos.

3. Ejecutar Servicio

Ventana de terminal
npm run start:dev

Verificación:

Ventana de terminal
curl http://localhost:3002/health
# Esperado: {"status":"ok"}

Microservicio de Proveedores

1. Clonar e Instalar

Ventana de terminal
cd ~/Documents/3A/Algesta
git clone <REPOSITORY_URL> algesta-ms-provider-nestjs
cd algesta-ms-provider-nestjs
npm install --force

2. Configurar Entorno

NODE_ENV=development
PORT=3003
MONGODB_URI=mongodb://localhost:27017/providers_ms
JWT_SECRET=your-dev-jwt-secret-min-32-chars
AZURE_STORAGE_CONNECTION_STRING=your-azure-storage-connection-string
AZURE_STORAGE_CONTAINER_NAME=documents-dev
REDIS_HOST=localhost
REDIS_PORT=6379

Nota: Para desarrollo local sin Azure, puedes usar almacenamiento de archivos local u omitir las cargas de documentos.

3. Ejecutar Servicio

Ventana de terminal
npm run start:dev

Verificación:

Ventana de terminal
curl http://localhost:3003/health
# Esperado: {"status":"ok"}

API Gateway

1. Clonar e Instalar

Ventana de terminal
cd ~/Documents/3A/Algesta
git clone <REPOSITORY_URL> algesta-api-gateway-nestjs
cd algesta-api-gateway-nestjs
npm install

2. Configurar Entorno

NODE_ENV=development
PORT=3000
MS_ORDERS_URL=http://localhost:3001
MS_NOTIFICATIONS_URL=http://localhost:3002
MS_PROVIDER_URL=http://localhost:3003
REDIS_HOST=localhost
REDIS_PORT=6379
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=60000
JWT_SECRET=your-dev-jwt-secret-min-32-chars

3. Ejecutar Servicio

Ventana de terminal
npm run start:dev

Verificación:

Ventana de terminal
curl http://localhost:3000/health
# Esperado: {"status":"ok","services":{"orders":"up","notifications":"up","provider":"up"}}

Acceder a la Documentación Swagger: Abre http://localhost:3000/api en tu navegador para explorar los endpoints de la API.

Dashboard (React SPA)

1. Clonar e Instalar

Ventana de terminal
cd ~/Documents/3A/Algesta
git clone <REPOSITORY_URL> algesta-dashboard-react
cd algesta-dashboard-react
pnpm install

Nota: El dashboard usa pnpm como su gestor de paquetes (versión 10.15.0).

2. Configurar Entorno

Crear archivo .env.local:

VITE_API_BASE_URL=http://localhost:3000
VITE_APP_TITLE=Algesta Dashboard
VITE_ENABLE_DEVTOOLS=true

3. Ejecutar Servidor de Desarrollo

Ventana de terminal
pnpm dev

Alternativa con acceso de red (para pruebas en otros dispositivos):

Ventana de terminal
pnpm dev:host

Verificación: Abre http://localhost:5173 en tu navegador. Deberías ver la página de inicio de sesión del Dashboard de Algesta.

4. Ejecutar Pruebas

Pruebas Unitarias (Vitest):

Ventana de terminal
pnpm test
# o con interfaz
pnpm test:ui

Pruebas E2E (Playwright):

Ventana de terminal
pnpm test:e2e
# o con interfaz de Playwright
pnpm test:e2e:ui

Configuración de Docker para Stack Completo

Por conveniencia, puedes ejecutar todos los servicios usando Docker Compose. Esto elimina la necesidad de gestionar servicios individuales.

Nota: Actualmente no existe un docker-compose.yml de stack completo en el código base. Cada microservicio tiene su propio archivo docker-compose. Puedes crear uno unificado basado en los archivos individuales.

Ejemplo de docker-compose.yml de Stack Completo (a crear en el directorio raíz de Algesta):

version: "3.8"


services:
  mongodb:
    image: mongo:7
    container_name: algesta-mongodb
    ports:
      - "27017:27017"
    volumes:
      - algesta-mongo-data:/data/db
    networks:
      - algesta-network
    healthcheck:
      test: ["CMD", "mongosh", "--eval", "db.adminCommand('ping')"]
      interval: 10s
      timeout: 5s
      retries: 5


  redis:
    image: redis:7-alpine
    container_name: algesta-redis
    ports:
      - "6379:6379"
    networks:
      - algesta-network
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 10s
      timeout: 5s
      retries: 5


  orders-ms:
    build:
      context: ./algesta-ms-orders-nestjs
      dockerfile: Dockerfile
    container_name: algesta-orders-ms
    depends_on:
      mongodb:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      - NODE_ENV=development
      - PORT=3001
      - MONGODB_URI=mongodb://mongodb:27017/orders_ms
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=dev-secret-minimum-32-characters-long
    ports:
      - "3001:3001"
    networks:
      - algesta-network
    volumes:
      - ./algesta-ms-orders-nestjs:/app
      - /app/node_modules


  notifications-ms:
    build:
      context: ./algesta-ms-notifications-nestjs
      dockerfile: Dockerfile
    container_name: algesta-notifications-ms
    depends_on:
      mongodb:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      - NODE_ENV=development
      - PORT=3002
      - MONGODB_URI=mongodb://mongodb:27017/notifications_ms
      - REDIS_HOST=redis
      - REDIS_PORT=6379
    ports:
      - "3002:3002"
    networks:
      - algesta-network


  provider-ms:
    build:
      context: ./algesta-ms-provider-nestjs
      dockerfile: Dockerfile
    container_name: algesta-provider-ms
    depends_on:
      mongodb:
        condition: service_healthy
      redis:
        condition: service_healthy
    environment:
      - NODE_ENV=development
      - PORT=3003
      - MONGODB_URI=mongodb://mongodb:27017/providers_ms
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=dev-secret-minimum-32-characters-long
    ports:
      - "3003:3003"
    networks:
      - algesta-network


  api-gateway:
    build:
      context: ./algesta-api-gateway-nestjs
      dockerfile: Dockerfile
    container_name: algesta-api-gateway
    depends_on:
      - orders-ms
      - notifications-ms
      - provider-ms
      - redis
    environment:
      - NODE_ENV=development
      - PORT=3000
      - MS_ORDERS_URL=http://orders-ms:3001
      - MS_NOTIFICATIONS_URL=http://notifications-ms:3002
      - MS_PROVIDER_URL=http://provider-ms:3003
      - REDIS_HOST=redis
      - REDIS_PORT=6379
      - JWT_SECRET=dev-secret-minimum-32-characters-long
    ports:
      - "3000:3000"
    networks:
      - algesta-network


volumes:
  algesta-mongo-data:


networks:
  algesta-network:
    driver: bridge

Para ejecutar el stack completo:

Ventana de terminal
cd ~/Documents/3A/Algesta
docker-compose up -d

Para detener el stack:

Ventana de terminal
docker-compose down

Para ver los logs:

Ventana de terminal
docker-compose logs -f
# o para un servicio específico
docker-compose logs -f orders-ms

Verificación:

Ventana de terminal
docker-compose ps
# Todos los servicios deben mostrar estado "Up"


curl http://localhost:3000/health
# Esperado: {"status":"ok","services":{...}}

Puertos de Servicio y Endpoints

ServicioPuertoEndpoint de SaludDocumentación Swagger
API Gateway3000http://localhost:3000/healthhttp://localhost:3000/api
Orders MS3001http://localhost:3001/healthhttp://localhost:3001/api
Notifications MS3002http://localhost:3002/healthhttp://localhost:3002/api
Provider MS3003http://localhost:3003/healthhttp://localhost:3003/api
Dashboard5173http://localhost:5173N/A (SPA)
MongoDB27017Conectar vía mongoshN/A
Redis6379redis-cli pingN/A

Nota: Todos los microservicios exponen documentación Swagger/OpenAPI en el endpoint /api para exploración interactiva de la API.

Comandos de Verificación

Después de configurar todos los servicios, ejecuta estos comandos para verificar que todo funciona:

1. Verificar Conexión a MongoDB

Ventana de terminal
mongosh --eval "show dbs"
# Esperado: Lista de bases de datos incluyendo orders_ms, notifications_ms, providers_ms

2. Verificar Conexión a Redis

Ventana de terminal
redis-cli ping
# Esperado: PONG

3. Health Check de Todos los Servicios

Ventana de terminal
# API Gateway
curl http://localhost:3000/health | jq .


# Orders MS
curl http://localhost:3001/health | jq .


# Notifications MS
curl http://localhost:3002/health | jq .


# Provider MS
curl http://localhost:3003/health | jq .

Esperado: Cada uno debe retornar {"status":"ok"} o similar.

4. Verificar Procesos en Ejecución

Ventana de terminal
# Verificar procesos de Node
ps aux | grep node


# Verificar contenedores Docker (si usas Docker)
docker ps


# Verificar uso de puertos
lsof -i :3000
lsof -i :3001
lsof -i :3002
lsof -i :3003
lsof -i :5173

5. Probar Enrutamiento del API Gateway

Ventana de terminal
# Probar creación de orden (requiere token de autenticación)
curl -X POST http://localhost:3000/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{"service":"Test Service","address":"Test Address","city":"Bogotá"}'

Nota: Necesitarás un token JWT válido. Consulta la Guía de Autenticación para detalles sobre cómo obtener tokens.

Próximos Pasos

Después de completar la configuración local, deberías:

  1. Leer la Documentación de Arquitectura: Comprende el diseño del sistema en Descripción General de Arquitectura

  2. Comprender los Requisitos del Negocio: Revisa el contexto del negocio y los requisitos en Documentación de Requisitos para entender el “por qué” detrás del sistema

  3. Configurar tu IDE: Configura linting, formateo y depuración

    • ESLint y Prettier están configurados en todos los repos
    • Configuraciones de VS Code están disponibles en los directorios .vscode/

  4. Ejecutar Pruebas: Asegúrate de que todas las pruebas pasen antes de hacer cambios

  5. Explorar la API: Usa la documentación Swagger para entender los endpoints disponibles

    • Gateway: http://localhost:3000/api
    • Servicios individuales: http://localhost:300X/api

  6. Configurar Git Hooks: Habilita hooks de pre-commit para calidad de código

    Ventana de terminal
    cd algesta-ms-orders-nestjs
    npm run prepare

  7. Revisar la Configuración de Entorno: Consulta la Guía de Configuración de Entorno para configuraciones similares a producción

  8. Comprender el Despliegue: Lee la Guía de Despliegue para aprender sobre pipelines CI/CD y despliegue en la nube

Guías Relacionadas:

Para Soporte:

  • Consulta la Guía de Solución de Problemas para problemas comunes
  • Revisa la Documentación de Arquitectura en wiki/02-architecture/
  • Contacta al líder del equipo para acceso a repositorios privados y credenciales