workspace-v1/core/devtools/environment/DEVENV-PORTS.md

Esquema de Puertos - ERP Suite

Version: 1.0.0 Fecha: 2025-12-06 Proposito: Asignacion centralizada de puertos para evitar conflictos entre proyectos

---

Principios de Asignacion

1. Rango base por proyecto: Cada proyecto tiene un offset de 100 puertos
2. Consistencia interna: Misma estructura de servicios en cada proyecto
3. Evitar puertos reservados: No usar puertos < 1024
4. Documentar cambios: Actualizar este archivo al agregar proyectos

---

Mapa de Puertos por Proyecto

Rango Base Asignado

Proyecto	Rango Base	Backend	Frontend	Database	Redis	MinIO	pgAdmin
erp-core	3000	3000	5173	5432	6379	9000/9001	5050
construccion	3100	3100	5174	5433	6380	9100/9101	5051
vidrio-templado	3200	3200	5175	5434	6381	9200/9201	5052
mecanicas-diesel	3300	3300	5176	5435	6382	9300/9301	5053
retail	3400	3400	5177	5436	6383	9400/9401	5054
clinicas	3500	3500	5178	5437	6384	9500/9501	5055
trading-platform	3600	3600	5179	5438	6385	9600/9601	5056
orbiquantia	3700	3700	5180	5439	6386	9700/9701	5057

---

Detalle por Proyecto

ERP Core (Base)

proyecto: erp-core
rango_base: 3000
servicios:
  backend:
    puerto: 3000
    protocolo: HTTP
    descripcion: API REST principal

  frontend_web:
    puerto: 5173
    protocolo: HTTP
    descripcion: Vite dev server (React)

  database:
    puerto: 5432
    protocolo: TCP
    descripcion: PostgreSQL 15+
    container: erp_core_db

  redis:
    puerto: 6379
    protocolo: TCP
    descripcion: Cache y colas
    container: erp_core_redis

  minio_api:
    puerto: 9000
    protocolo: HTTP
    descripcion: S3-compatible storage API

  minio_console:
    puerto: 9001
    protocolo: HTTP
    descripcion: MinIO Web Console

  pgadmin:
    puerto: 5050
    protocolo: HTTP
    descripcion: Database admin UI (opcional)

Construccion (Vertical)

proyecto: construccion
rango_base: 3100
servicios:
  backend:
    puerto: 3100
    protocolo: HTTP
    descripcion: API REST construccion

  frontend_web:
    puerto: 5174
    protocolo: HTTP
    descripcion: Vite dev server (React)

  database:
    puerto: 5433
    protocolo: TCP
    descripcion: PostgreSQL 15+ con PostGIS
    container: erp_construccion_db

  redis:
    puerto: 6380
    protocolo: TCP
    descripcion: Cache y colas
    container: erp_construccion_redis

  minio_api:
    puerto: 9100
    protocolo: HTTP
    descripcion: S3-compatible storage API

  minio_console:
    puerto: 9101
    protocolo: HTTP
    descripcion: MinIO Web Console

  pgadmin:
    puerto: 5051
    protocolo: HTTP
    descripcion: Database admin UI (opcional)

---

Variables de Entorno Estandar

Template .env para cada proyecto

# ===========================================
# PROYECTO: {NOMBRE_PROYECTO}
# RANGO BASE: {RANGO}
# ===========================================

# Application
NODE_ENV=development
APP_PORT={BACKEND_PORT}
APP_HOST=0.0.0.0
API_VERSION=v1
API_PREFIX=/api/v1

# Database
DB_HOST=localhost
DB_PORT={DB_PORT}
DB_NAME={db_name}
DB_USER={db_user}
DB_PASSWORD={db_password}
DATABASE_URL=postgresql://${DB_USER}:${DB_PASSWORD}@${DB_HOST}:${DB_PORT}/${DB_NAME}

# Redis
REDIS_HOST=localhost
REDIS_PORT={REDIS_PORT}
REDIS_URL=redis://${REDIS_HOST}:${REDIS_PORT}

# MinIO (S3)
S3_ENDPOINT=http://localhost:{MINIO_API_PORT}
S3_ACCESS_KEY=minioadmin
S3_SECRET_KEY=minioadmin
S3_BUCKET={bucket_name}

# JWT
JWT_SECRET=your-super-secret-jwt-key-change-in-production
JWT_EXPIRATION=24h
JWT_REFRESH_EXPIRATION=7d

# CORS
CORS_ORIGIN=http://localhost:{FRONTEND_PORT}
CORS_CREDENTIALS=true

# Frontend (para Vite)
VITE_API_URL=http://localhost:${APP_PORT}
VITE_WS_URL=ws://localhost:${APP_PORT}

---

Valores Especificos por Proyecto

erp-core

APP_PORT=3000
DB_PORT=5432
DB_NAME=erp_core
REDIS_PORT=6379
S3_ENDPOINT=http://localhost:9000
CORS_ORIGIN=http://localhost:5173
VITE_API_URL=http://localhost:3000

construccion

APP_PORT=3100
DB_PORT=5433
DB_NAME=erp_construccion
REDIS_PORT=6380
S3_ENDPOINT=http://localhost:9100
CORS_ORIGIN=http://localhost:5174
VITE_API_URL=http://localhost:3100

---

Docker Compose Networking

Red compartida vs aislada

Opcion 1: Redes aisladas (RECOMENDADO para desarrollo)

• Cada proyecto tiene su propia red
• No hay conflictos de nombres de contenedor
• Facilita pruebas independientes

# Ejemplo para construccion
networks:
  erp_construccion_network:
    driver: bridge
    name: erp_construccion_network

Opcion 2: Red compartida (para integracion)

• Todos los proyectos en una red
• Comunicacion directa entre servicios
• Requiere nombres de contenedor unicos

networks:
  erp_suite_network:
    external: true
    name: erp_suite_network

---

Validacion de Puertos

Script de verificacion

#!/bin/bash
# validate-ports.sh
# Verifica que los puertos asignados esten disponibles

PORTS=(
  3000 3100 3200 3300 3400 3500 3600 3700  # Backend
  5173 5174 5175 5176 5177 5178 5179 5180  # Frontend
  5432 5433 5434 5435 5436 5437 5438 5439  # Database
  6379 6380 6381 6382 6383 6384 6385 6386  # Redis
)

echo "Verificando disponibilidad de puertos..."

for port in "${PORTS[@]}"; do
  if lsof -Pi :$port -sTCP:LISTEN -t >/dev/null 2>&1; then
    echo "OCUPADO: Puerto $port en uso"
  else
    echo "OK: Puerto $port disponible"
  fi
done

---

Reglas de Asignacion

Al agregar nuevo proyecto

1. Asignar siguiente rango base disponible (incremento de 100)
2. Actualizar tabla de puertos en este documento
3. Crear docker-compose.yml con puertos correctos
4. Crear .env.example con variables correctas
5. Ejecutar script de validacion

Puertos reservados (NO USAR)

Puerto	Razon
22	SSH
80	HTTP standard
443	HTTPS standard
3306	MySQL (evitar confusion)
5000	Flask default
8080	Tomcat/proxies
8443	HTTPS alternativo

---

Troubleshooting

Puerto ocupado

# Encontrar proceso usando puerto
lsof -i :3000

# Matar proceso por PID
kill -9 <PID>

# O usando fuser
fuser -k 3000/tcp

Verificar contenedores Docker

# Ver puertos mapeados
docker ps --format "table {{.Names}}\t{{.Ports}}"

# Detener todos los contenedores de un proyecto
docker-compose -f docker-compose.yml down

---

Changelog

v1.0.0 (2025-12-06)

• Definicion inicial de esquema de puertos
• Asignacion para 8 proyectos
• Templates de .env y docker-compose
• Script de validacion

---

Mantenido por: DevEnv-Agent Ultima actualizacion: 2025-12-06