rikrdo/mercadodevida
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
506dfd0cce19549226bf02fef0c38d0bd1e41615
mercadodevida/docs/HOWTO-monolith.md
chattie e86034a62c feat(F-049): completed feature
2026-08-19 07:34:15 +02:00

6.8 KiB
Raw Blame History

HOWTO — operar MercadoDeVida en desarrollo y producción local

Esta guía levanta el monolito completo en una máquina y lo publica en la red local (LAN):

Servicio Puerto Descripción
Backend 3000 API Fastify, health y Swagger
Frontend 3003 Tienda principal para clientes
Admin 3004 Backoffice
Storefront 3005 Storefront SEO/ISR
PostgreSQL 5432 Base de datos de infraestructura
Redis 6379 Cache/infraestructura

El punto de entrada operativo es:

cd /ruta/al/repo/project
./scripts/monolith.sh <dev|prod> <comando>

Comandos disponibles:

start    instala, migra y levanta todos los servicios
restart  detiene los procesos gestionados y hace start completo
status   muestra PID, estado del proceso, HTTP y URL LAN
stop     detiene los cuatro procesos HTTP gestionados
logs     sigue todos los logs; Ctrl-C deja servicios ejecutándose
urls     imprime URLs locales y LAN sin cambiar procesos

Los PID y logs se guardan en project/.runtime/<modo>/ y no se versionan.

1. Requisitos

  • Node.js 22 o superior.
  • npm.
  • Docker Desktop/Engine con docker compose.
  • Puertos libres: 3000, 3003, 3004, 3005.
  • Para acceso desde otro dispositivo: ambos equipos en la misma LAN y firewall permitiendo conexiones entrantes a esos puertos.

Comprobar:

node --version
docker --version
docker compose version

El script crea project/.env sólo si falta, usando valores locales de desarrollo. Para una instalación real de producción, proporcionar un .env propio y secretos externos al repositorio.

Variables importantes del backend:

DATABASE_URL=postgres://...
REDIS_URL=redis://...
HOST=0.0.0.0
PORT=3000
COOKIE_SECURE=false

COOKIE_SECURE=false sólo es apropiado para HTTP dentro de una LAN de confianza. En producción pública debe usarse HTTPS y COOKIE_SECURE=true detrás de un reverse proxy.

2. Desarrollo

Levantar

cd project
./scripts/monolith.sh dev start

El comando comprueba puertos, levanta PostgreSQL/Redis, instala dependencias, aplica migraciones y arranca backend y las tres aplicaciones Next con binding LAN.

Reiniciar

./scripts/monolith.sh dev restart

Estado

./scripts/monolith.sh dev status

status muestra PID, proceso, HTTP y URL; devuelve código distinto de cero si algún servicio falla.

Logs

./scripts/monolith.sh dev logs

Logs individuales:

tail -F .runtime/dev/backend.log
tail -F .runtime/dev/admin.log
tail -F .runtime/dev/frontend.log
tail -F .runtime/dev/storefront.log

Detener

./scripts/monolith.sh dev stop

PostgreSQL y Redis continúan. Para detenerlos:

docker compose stop postgres redis

Para eliminar contenedores conservando volúmenes:

docker compose down

No usar docker compose down -v salvo que se quiera eliminar la base local.

3. Producción local/LAN

Este modo ejecuta builds optimizados y next start. Es adecuado para una máquina persistente en una LAN. No sustituye HTTPS, supervisor del sistema, backups ni reverse proxy de una producción pública.

Build + migraciones + levantar

cd project
./scripts/monolith.sh prod start

Usa npm ci, aplica migraciones, construye backend/admin/frontend/storefront y arranca todo en 0.0.0.0.

Redeploy / reinicio completo

cd project
./scripts/monolith.sh prod restart

Detiene únicamente PIDs registrados en .runtime/prod/; nunca usa pkill global. Si un puerto está ocupado por un proceso ajeno, falla y muestra el PID.

Estado, logs y stop

./scripts/monolith.sh prod status
./scripts/monolith.sh prod logs
./scripts/monolith.sh prod stop
./scripts/monolith.sh prod urls

Logs individuales:

tail -F .runtime/prod/backend.log
tail -F .runtime/prod/admin.log
tail -F .runtime/prod/frontend.log
tail -F .runtime/prod/storefront.log

4. Acceso desde otro dispositivo de la LAN

IP detectada actualmente:

192.168.18.93

URLs:

  • Tienda principal: http://192.168.18.93:3003/
  • Backoffice: http://192.168.18.93:3004/
  • Storefront SEO: http://192.168.18.93:3005/
  • Backend health: http://192.168.18.93:3000/health
  • Swagger/OpenAPI: http://192.168.18.93:3000/docs

La IP DHCP puede cambiar. Consultar la actual:

./scripts/monolith.sh prod urls

Forzar una IP concreta:

LAN_IP=192.168.18.93 ./scripts/monolith.sh prod restart

Diagnóstico desde el host:

curl -i http://127.0.0.1:3000/health
curl -I http://192.168.18.93:3003/

Desde el otro dispositivo:

curl -i http://192.168.18.93:3000/health

Si local funciona pero LAN no:

  1. confirmar status con HTTP 200;
  2. confirmar que ambos dispositivos están en la misma red y no una guest aislada;
  3. permitir conexiones entrantes de Node/Docker en el firewall;
  4. comprobar que el router no tiene client isolation;
  5. inspeccionar listeners:
lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(3000|3003|3004|3005)\b'

5. Infraestructura y base de datos

docker ps
docker compose ps
docker exec mdv-dev-postgres pg_isready -U mdv -d mercadodevida
npm run db:status

Aplicar migraciones manualmente:

node --env-file-if-exists=.env node_modules/node-pg-migrate/bin/node-pg-migrate.js up --migrations-dir migrations

Logs:

docker logs -f mdv-dev-postgres
docker logs -f mdv-dev-redis

6. Validación antes/después del deploy

Desde la raíz:

./scripts/verify.sh

Desde project/:

npm run lint
npm run lint:boundaries
npm run typecheck
npm test
npm run build
(cd apps/admin && npm run lint && npm run typecheck && npm run build)
(cd frontend && npm run lint && npm run build)
(cd storefront && npm run lint && npm run typecheck && npm run build)

Smoke test:

./scripts/monolith.sh prod status
curl -fsS http://127.0.0.1:3000/health
curl -fsS -o /dev/null http://127.0.0.1:3003/
curl -fsS -o /dev/null http://127.0.0.1:3004/
curl -fsS -o /dev/null http://127.0.0.1:3005/

7. Problemas frecuentes

Puerto ocupado por proceso no gestionado

lsof -nP -iTCP:3000 -sTCP:LISTEN
ps -p <PID> -o pid,ppid,command

Detenerlo explícitamente y repetir. El script no mata procesos no registrados.

Backend no arranca

tail -100 .runtime/prod/backend.log
docker exec mdv-dev-postgres pg_isready -U mdv -d mercadodevida

Revisar DATABASE_URL en .env.

Un frontend usa localhost desde otro dispositivo

LAN_IP=<IP_DEL_HOST> ./scripts/monolith.sh prod restart

NEXT_PUBLIC_API_URL se incorpora durante el build, por lo que cambiar IP requiere reconstruir producción.

Cambiar puertos

BACKEND_PORT=3100 FRONTEND_PORT=3103 ADMIN_PORT=3104 STOREFRONT_PORT=3105 \
  ./scripts/monolith.sh prod restart

Usar los mismos overrides en todos los comandos posteriores.