wallabicher/web/DEVELOPMENT.md

Guía de Desarrollo

Configuración de Puertos

Desarrollo Local

Servicio	Puerto	URL
Dashboard (Vue)	3000	http://localhost:3000
Backend (API)	3001	http://localhost:3001
Landing (Astro)	3002	http://localhost:3002

Producción (Docker)

Servicio	Puerto Externo	Puerto Interno
Nginx Proxy	80	-
Dashboard	-	80
Backend	-	3001
Landing	-	80

Ejecutar en Desarrollo Local

1. Backend (API)

cd web/backend
npm install
npm run dev

El backend estará disponible en http://localhost:3001

Endpoints:

• API: http://localhost:3001/api/*
• WebSocket: ws://localhost:3001/ws

2. Dashboard (Vue)

cd web/dashboard
npm install
npm run dev

El dashboard estará disponible en http://localhost:3000

Nota: Vite está configurado con proxy automático:

• /api/* → http://localhost:3001/api/*
• /ws → ws://localhost:3001/ws

Esto significa que puedes hacer peticiones a /api/users desde el dashboard y automáticamente se redirigirán al backend.

3. Landing (Astro)

cd web/landing
npm install
npm run dev

La landing estará disponible en http://localhost:3002

Ejecutar con Docker (Producción)

# Construir imágenes
docker-compose build

# Iniciar servicios
docker-compose up -d

# Ver logs
docker-compose logs -f

# Detener servicios
docker-compose down

Todo estará disponible en http://localhost:

• Landing: http://localhost/
• Dashboard: http://localhost/dashboard/
• API: http://localhost/api/

Reconstruir después de cambios

Cambios en código (desarrollo)

No es necesario hacer nada, Vite y Node tienen hot-reload automático.

Cambios en configuración o Docker

# Reconstruir servicio específico
docker-compose build dashboard
docker-compose build backend
docker-compose build landing

# Reconstruir todo
docker-compose build

# Reiniciar servicios
docker-compose up -d

Diferencias entre Desarrollo y Producción

Dashboard

• Desarrollo:

  • Puerto 3000
  • Vite proxy activo para /api y /ws
  • Hot Module Replacement (HMR)
  • Source maps

• Producción:

  • Puerto 80 (interno)
  • Sin proxy (nginx principal maneja todo)
  • Código minificado y optimizado
  • Assets con hash para cache

Backend

• Desarrollo:

  • Puerto 3001
  • node --watch para auto-reload
  • Variables de entorno por defecto

• Producción:

  • Puerto 3001 (interno)
  • node sin watch
  • Variables de entorno de Docker

Landing

• Desarrollo:

  • Puerto 3002
  • Servidor de desarrollo de Astro
  • Hot reload

• Producción:

  • Puerto 80 (interno)
  • Archivos estáticos servidos por nginx
  • Pre-renderizado

Troubleshooting

Puerto ya en uso

# Ver qué está usando el puerto
lsof -i :3000  # Dashboard
lsof -i :3001  # Backend
lsof -i :3002  # Landing

# Matar proceso
kill -9 <PID>

Proxy no funciona en desarrollo

Asegúrate de que:

1. El backend está corriendo en el puerto 3001
2. Estás ejecutando npm run dev (modo desarrollo)
3. La configuración de proxy en vite.config.js está correcta

Assets 404 en producción

Ver NGINX_CONFIG.md para detalles de configuración de nginx y assets.

Variables de Entorno

Backend (desarrollo local)

Crear archivo .env en web/backend/:

PORT=3001
PROJECT_ROOT=/ruta/al/proyecto
MONGODB_HOST=localhost
MONGODB_PORT=27017
MONGODB_DATABASE=wallabicher
MONGODB_USERNAME=admin
MONGODB_PASSWORD=adminpassword

Backend (Docker)

Las variables se configuran en docker-compose.yml:

• PORT=3001
• PROJECT_ROOT=/data
• Credenciales de MongoDB

Base URLs

Dashboard

La configuración de base: '/dashboard/' en vite.config.js hace que:

• Todos los assets se construyan con prefijo /dashboard/
• Vue Router use /dashboard como base
• Service Worker se registre en /dashboard/sw.js

No cambiar a menos que quieras cambiar la ruta del dashboard.

Landing

Sin base (raíz por defecto). Se sirve desde /.

No cambiar a menos que quieras mover la landing a otra ruta.