feat(F-049): completed feature
This commit is contained in:
chattie
319
docs/HOWTO-monolith.md
Normal file
319
docs/HOWTO-monolith.md
Normal file
@@ -0,0 +1,319 @@
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
cd /ruta/al/repo/project
|
||||
./scripts/monolith.sh <dev|prod> <comando>
|
||||
```
|
||||
|
||||
Comandos disponibles:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```dotenv
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh dev restart
|
||||
```
|
||||
|
||||
### Estado
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh dev status
|
||||
```
|
||||
|
||||
`status` muestra PID, proceso, HTTP y URL; devuelve código distinto de cero si algún servicio falla.
|
||||
|
||||
### Logs
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh dev logs
|
||||
```
|
||||
|
||||
Logs individuales:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh dev stop
|
||||
```
|
||||
|
||||
PostgreSQL y Redis continúan. Para detenerlos:
|
||||
|
||||
```bash
|
||||
docker compose stop postgres redis
|
||||
```
|
||||
|
||||
Para eliminar contenedores conservando volúmenes:
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh prod status
|
||||
./scripts/monolith.sh prod logs
|
||||
./scripts/monolith.sh prod stop
|
||||
./scripts/monolith.sh prod urls
|
||||
```
|
||||
|
||||
Logs individuales:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```text
|
||||
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:
|
||||
|
||||
```bash
|
||||
./scripts/monolith.sh prod urls
|
||||
```
|
||||
|
||||
Forzar una IP concreta:
|
||||
|
||||
```bash
|
||||
LAN_IP=192.168.18.93 ./scripts/monolith.sh prod restart
|
||||
```
|
||||
|
||||
Diagnóstico desde el host:
|
||||
|
||||
```bash
|
||||
curl -i http://127.0.0.1:3000/health
|
||||
curl -I http://192.168.18.93:3003/
|
||||
```
|
||||
|
||||
Desde el otro dispositivo:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
lsof -nP -iTCP -sTCP:LISTEN | grep -E ':(3000|3003|3004|3005)\b'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Infraestructura y base de datos
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
docker compose ps
|
||||
docker exec mdv-dev-postgres pg_isready -U mdv -d mercadodevida
|
||||
npm run db:status
|
||||
```
|
||||
|
||||
Aplicar migraciones manualmente:
|
||||
|
||||
```bash
|
||||
node --env-file-if-exists=.env node_modules/node-pg-migrate/bin/node-pg-migrate.js up --migrations-dir migrations
|
||||
```
|
||||
|
||||
Logs:
|
||||
|
||||
```bash
|
||||
docker logs -f mdv-dev-postgres
|
||||
docker logs -f mdv-dev-redis
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Validación antes/después del deploy
|
||||
|
||||
Desde la raíz:
|
||||
|
||||
```bash
|
||||
./scripts/verify.sh
|
||||
```
|
||||
|
||||
Desde `project/`:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user