# 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.
