Quick start — desarrollo local

Guía para levantar el backend de ConectaMed en tu máquina con Docker Compose. El panel NOC (ui/nwi-app-conectamed-noc-web) y el monitor-worker suelen ejecutarse en el host apuntando al mismo .env y Redis/Soketi del compose.

Requisitos

• Docker Engine + Docker Compose v2
• Node.js ≥ 20 (para frontends y workers en host)
• Token de GitHub Packages con lectura del paquete @observer-ltda/conectamed-lib-common
• Puertos libres: 5432, 6379, 6001, 3001–3007, 8080, 1812/udp, 1813/udp

1. Clonar y ubicarse en el monorepo

cd /ruta/a/0_repos/services

Estructura esperada (extracto):

services/
  docker-compose.dev.yml      # Orquestación dev (canónico)
  .env                        # Tu copia local (no commitear)
  nwi-app-conectamed-auth-ms/
  nwi-app-conectamed-bff/
  nwi-app-conectamed-captive-portal-ms/
  nwi-app-conectamed-inventory-ms/
  ...
  nwi-app-conectamed-docs-core/
    docs/tecnico/desarrollo/ejemplos/   # Plantillas de referencia

2. Crear .env desde el ejemplo

Copia la plantilla sin secretos reales incluida en esta documentación:

cp nwi-app-conectamed-docs-core/docs/tecnico/desarrollo/ejemplos/env.dev.example .env

Edita al menos:

Variable	Descripción
DB_PASSWORD	Contraseña Postgres del compose
JWT_SECRET	Secreto JWT (cadena larga aleatoria)
GITHUB_TOKEN	PAT para npm install de lib-common en el build
INTELLIGENCE_WORKER_INTERNAL_API_KEY / RADIUS_WORKER_INTERNAL_API_KEY	Claves internas BFF ↔ workers
OPENAI_API_KEY o ANTHROPIC_API_KEY	Solo si usas Smart Question
INTELLIGENCE_ENCRYPTION_KEY	openssl rand -base64 32 si cifras API keys en BD

Ejemplo .env (valores ficticios)

.env — ejemplo

NODE_ENV=local

DB_PORT=5432
DB_AUTH_NAME=conectamed-auth
DB_INVENTORY_NAME=conectamed-inventory
DB_CAPTIVE_PORTAL_NAME=conectamed-captive-portal
DB_INTELLIGENCE_NAME=conectamed-intelligence

DB_HOST=postgres
DB_USER=app
DB_PASSWORD=change-me-db-password
DB_SSL_ENABLED=false
DB_NAME=appdb

AUTH_SERVICE_URL=http://nwi-app-conectamed-auth-ms:3001/v1
CAPTIVE_PORTAL_SERVICE_URL=http://nwi-app-conectamed-captive-portal-ms:3002/v1
INVENTORY_SERVICE_URL=http://nwi-app-conectamed-inventory-ms:3003/v1
INTELLIGENCE_WORKER_SERVICE_URL=http://intelligence-worker:3007/v1
INTELLIGENCE_WORKER_INTERNAL_API_KEY=change-me-intelligence-internal-key

LLM_PROVIDER=openai
OPENAI_API_KEY=sk-example-not-a-real-key
INTELLIGENCE_ENCRYPTION_KEY=base64-example-key-32-bytes-min=

JWT_SECRET=change-me-jwt-secret-use-long-random-string
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

SOKETI_DEFAULT_APP_ID=conectamed
SOKETI_DEFAULT_APP_KEY=conectamed-app-key-dev
SOKETI_DEFAULT_APP_SECRET=conectamed-app-secret-dev
SOKETI_HOST_PORT=6001

PASSWORD_RESET_APP_URL=http://localhost:9060
TZ=America/Bogota

aviso

Nunca subas .env con tokens, SMTP ni claves de Metabase al repositorio. El archivo real vive solo en tu disco.

3. Levantar servicios con Docker Compose

El archivo canónico está en la raíz de services/:

docker compose -f docker-compose.dev.yml up -d --build

Plantilla equivalente documentada (misma estructura):
ejemplos/docker-compose.dev.example.yml

Servicios incluidos

Servicio Compose	Puerto host	Función
postgres	5432	PostgreSQL (varias BDs vía init scripts)
redis	6379	Cache, sesiones, colas
soketi	6001	WebSockets (Pusher-compatible)
auth-service	3001	Usuarios y roles
captive-portal-service	3002	Portal cautivo API
inventory-service	3003	Inventario y mapa
worker-radius	3004	Integración RADIUS
notification-service	3005	Correo SMTP
bff-api	8080	API unificada /v1
intelligence-worker	3007	Smart Question / IA
radius-server	1812/1813 udp	FreeRADIUS

Extracto docker-compose.dev.yml (referencia)

docker-compose.dev.yml (extracto)

name: conectamed-dev

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: ${DB_USER:-app}
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set in .env}
      POSTGRES_DB: ${DB_NAME:-appdb}
    ports:
      - "5432:5432"
    volumes:
      - ./docker/postgres-init:/docker-entrypoint-initdb.d:ro

  bff-api:
    build:
      context: ./nwi-app-conectamed-bff
      dockerfile: Dockerfile.dev
      args:
        GITHUB_TOKEN: ${GITHUB_TOKEN}
    ports:
      - "8080:8080"
    environment:
      AUTH_SERVICE_URL: ${AUTH_SERVICE_URL:-http://auth-service:3001/v1}
      INVENTORY_SERVICE_URL: ${INVENTORY_SERVICE_URL:-http://inventory-service:3003/v1}
      REDIS_HOST: redis
    depends_on:
      - auth-service
      - inventory-service

  # … auth-service, inventory-service, redis, soketi, workers, radius-server

El archivo completo está en el repositorio y en ejemplos/docker-compose.dev.example.yml.

4. Comprobar que el stack responde

# BFF (ajusta la ruta de health si tu BFF expone /health o /v1/...)
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:8080/

docker compose -f docker-compose.dev.yml ps
docker compose -f docker-compose.dev.yml logs -f bff-api

Migraciones: cada microservicio Nest suele ejecutarlas al arrancar (TYPEORM_MIGRATIONS en el compose) o vía script del README del MS.

5. Panel NOC (frontend)

En otro terminal, desde el UI del monorepo:

cd ../ui/nwi-app-conectamed-noc-web
cp .env.example .env.local   # si existe; define NEXT_PUBLIC_API_BASE_URL
# NEXT_PUBLIC_API_BASE_URL=http://localhost:8080/v1
npm install
npm run dev

Abre la URL que indique Next (p. ej. http://localhost:9060) y alinea PASSWORD_RESET_APP_URL en .env del compose con esa URL.

6. Monitor worker (opcional)

nwi-app-conectamed-monitor-worker suele correr fuera del compose para pings y alertas en vivo. Usa REDIS_HOST=localhost, INVENTORY_SERVICE_URL=http://localhost:3003/v1 y la misma configuración Soketi que en .env raíz. Consulta el README de ese repositorio.

Parar y limpiar

docker compose -f docker-compose.dev.yml down
# Volúmenes (borra datos locales de Postgres/Redis):
# docker compose -f docker-compose.dev.yml down -v

Siguiente paso

• Mapa de servicios — puertos y repos
• Infraestructura AWS — despliegue staging/prod con Terraform