320 lines
6.8 KiB
Markdown
320 lines
6.8 KiB
Markdown
# 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.
|