Guia de Desarrollo Local

Guia practica paso a paso para configurar el entorno de desarrollo local de Nvito, incluyendo los tres repositorios, servicios Docker y herramientas de apoyo.

1. Prerequisitos

Antes de comenzar, asegurate de tener instaladas las siguientes herramientas:

1.1 Verificar instalaciones

node --version    # v20.x.x
npm --version     # 10.x.x
docker --version  # Docker version 2x.x.x
git --version     # git version 2.x.x

Asegurate de que Docker Desktop este en ejecucion antes de continuar.

2. Setup Paso a Paso

2.1 Instalar bws CLI (Bitwarden Secrets Manager)

El proyecto utiliza Bitwarden Secrets Manager para gestionar secretos. El CLI bws inyecta variables de entorno en tiempo de ejecucion sin necesidad de archivos .env con secretos reales.

# macOS (descarga directa)
curl -fsSL "https://github.com/bitwarden/sdk-sm/releases/latest/download/bws-aarch64-apple-darwin.zip" -o bws.zip
unzip bws.zip -d /tmp/bws && mv /tmp/bws/bws ~/.local/bin/bws && chmod +x ~/.local/bin/bws
rm bws.zip

# Agregar a ~/.zshrc
export BWS_ACCESS_TOKEN="<token del machine account local-dev>"
export BWS_PROJECT_LOCAL="<project ID de nvito-local>"

# Recargar shell y verificar
source ~/.zshrc
bws secret list

Solicita al administrador del proyecto el BWS_ACCESS_TOKEN y el BWS_PROJECT_LOCAL correspondientes al machine account local-dev.

2.2 Clonar los repositorios

Clona los tres repositorios en un mismo directorio padre para mantener la estructura organizada:

mkdir -p ~/desarrollo/Nvito && cd ~/desarrollo/Nvito

git clone <url-repo>/nvito-api.git
git clone <url-repo>/nvito-admin.git
git clone <url-repo>/nvito-invitations.git

2.3 Instalar dependencias

Ejecuta npm install en cada proyecto:

cd ~/desarrollo/Nvito/nvito-api && npm install
cd ~/desarrollo/Nvito/nvito-admin && npm install
cd ~/desarrollo/Nvito/nvito-invitations && npm install

2.4 Crear volumenes Docker (primera vez)

El docker-compose.yml del API utiliza volumenes externos. Deben crearse una sola vez:

docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data

2.5 Levantar servicios Docker

Desde el directorio del API, levantar la infraestructura local:

cd ~/desarrollo/Nvito/nvito-api
npm run docker:up

Esto levanta los siguientes contenedores:

Verifica que todos los contenedores esten corriendo:

docker ps

2.6 Configurar variables de entorno

Cada proyecto tiene archivos de entorno preconfigurados para desarrollo local:

# En nvito-api
cd ~/desarrollo/Nvito/nvito-api
npm run env:dev

# En nvito-admin
cd ~/desarrollo/Nvito/nvito-admin
npm run env:dev

# En nvito-invitations
cd ~/desarrollo/Nvito/nvito-invitations
npm run env:dev

Estos comandos copian el archivo config/environments/.env.development a .env en la raiz de cada proyecto.

2.7 Ejecutar migraciones y seed (nvito-api)

cd ~/desarrollo/Nvito/nvito-api

# Generar el cliente Prisma
npm run db:generate

# Aplicar migraciones a la base de datos local
npm run db:migrate

# Poblar datos iniciales (Super Admin, Event Types, Packages, Templates)
npm run db:seed

Alternativamente, el comando setup ejecuta todo el flujo completo:

npm run setup
# Equivale a: env:dev -> docker:up -> (espera 5s) -> db:generate -> db:migrate -> db:seed

2.8 Iniciar los servicios

Abre tres terminales separadas y ejecuta cada servicio. Si los secretos se gestionan via Bitwarden, utiliza los comandos dev:bws:

Terminal 1 -- API (NestJS):

cd ~/desarrollo/Nvito/nvito-api
npm run dev:bws
# O sin Bitwarden: npm run start:dev

Terminal 2 -- Admin (Next.js):

cd ~/desarrollo/Nvito/nvito-admin
npm run dev:bws
# O sin Bitwarden: npm run dev

Terminal 3 -- Invitations (Next.js):

cd ~/desarrollo/Nvito/nvito-invitations
npm run dev:bws
# O sin Bitwarden: npm run dev

2.9 Instalar hooks de Git

Cada repositorio incluye un script para instalar hooks de pre-commit (gitleaks para deteccion de secretos):

cd ~/desarrollo/Nvito/nvito-api && npm run hooks:install
cd ~/desarrollo/Nvito/nvito-admin && npm run hooks:install
cd ~/desarrollo/Nvito/nvito-invitations && npm run hooks:install

3. Comandos Utiles

3.1 nvito-api (NestJS + Prisma)

3.2 nvito-admin (Next.js)

3.3 nvito-invitations (Next.js)

4. URLs Locales

Una vez que todos los servicios estan corriendo, estas son las URLs disponibles:

4.1 Aplicaciones

4.2 Herramientas de infraestructura

4.3 Servicios internos (sin UI web)

5. Troubleshooting

5.1 Docker Compose falla al iniciar

Problema: Error volume "invitia-api_postgres_data" not found

Solucion: Los volumenes son externos y deben crearse manualmente la primera vez:

docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data

5.2 Puerto ya en uso

Problema: Error: listen EADDRINUSE: address already in use :::3000

Solucion: Identificar y detener el proceso que ocupa el puerto:

# Buscar el proceso
lsof -i :3000

# Terminar el proceso
kill -9 <PID>

Puertos comunes que pueden entrar en conflicto: 3000 (API), 5050 (Admin), 3001 (Invitations), 5432 (PostgreSQL), 6379 (Redis), 8080 (Adminer).

5.3 Prisma: migraciones fallan

Problema: Error: P3009 — migrate found failed migrations

Solucion: Reiniciar la base de datos desde cero:

npm run docker:clean    # Elimina contenedores y volumenes
# Recrear volumenes
docker volume create invitia-api_postgres_data
docker volume create invitia-api_redis_data
docker volume create invitia-api_minio_data
npm run setup           # Levanta todo de nuevo con datos limpios

5.4 Error de conexion a PostgreSQL

Problema: Error: P1001 — Can't reach database server at localhost:5432

Solucion: Verificar que el contenedor de PostgreSQL este corriendo y saludable:

docker ps | grep nvito-postgres
docker logs nvito-postgres

Si el contenedor no aparece, levantar los servicios de nuevo:

npm run docker:up

5.5 bws: comando no encontrado

Problema: zsh: command not found: bws

Solucion: Verificar que bws este en el PATH:

# Verificar ubicacion
ls ~/.local/bin/bws

# Si existe pero no esta en PATH, agregar a ~/.zshrc:
export PATH="$HOME/.local/bin:$PATH"
source ~/.zshrc

5.6 bws: token invalido o expirado

Problema: Error: Unauthorized al ejecutar bws secret list

Solucion: Solicitar un nuevo access token al administrador del proyecto y actualizar la variable BWS_ACCESS_TOKEN en ~/.zshrc.

5.7 MinIO: buckets no se crean automaticamente

Problema: El contenedor nvito-minio-client sale con error.

Solucion: Verificar que MinIO este saludable antes de que el client intente conectarse:

docker logs nvito-minio-client
# Si fallo, reiniciar solo el client:
docker restart nvito-minio-client

Los buckets que deben existir son: nvito-uploads, nvito-assets, nvito-private, nvito-templates.

5.8 Emails no aparecen en MailDev

Problema: Al enviar un email desde el API, no aparece en http://localhost:1080.

Solucion: Verificar que el .env del API tenga la configuracion SMTP apuntando a MailDev:

SMTP_HOST=localhost
SMTP_PORT=1025

MailDev no requiere autenticacion. Si las variables SMTP_USER y SMTP_PASSWORD estan vacias, nodemailer omite la autenticacion automaticamente.

5.9 Next.js: cambios en variables NEXT_PUBLIC no se reflejan

Problema: Despues de modificar una variable NEXT_PUBLIC_*, el frontend sigue usando el valor anterior.

Solucion: Las variables con prefijo NEXT_PUBLIC_ se inyectan en build time. Es necesario reiniciar el servidor de desarrollo:

# Detener el proceso (Ctrl+C) y volver a iniciar
npm run dev

6. Tips de Desarrollo

6.1 Hot Reload

Los tres proyectos soportan hot reload en modo desarrollo:

• nvito-api: nest start --watch recompila automaticamente al detectar cambios en archivos .ts. Se activa con npm run start:dev.
• nvito-admin: Next.js Fast Refresh actualiza la pagina sin perder el estado de React.
• nvito-invitations: Mismo comportamiento de Fast Refresh de Next.js.

Nota: Los cambios en el schema de Prisma (prisma/schema.prisma) requieren regenerar el cliente manualmente:

npm run db:generate

Si se agregan nuevas migraciones, ejecutar tambien:

npm run db:migrate

6.2 Debugging del API

Para depurar el backend con breakpoints desde VS Code:

1. Iniciar el API en modo debug:

   npm run start:debug
   # O con Bitwarden: npm run dev:bws:debug
   

2. En VS Code, abrir la paleta de comandos y seleccionar Debug: Attach to Node Process.
3. Seleccionar el proceso de NestJS (puerto 9229).

Alternativamente, agregar esta configuracion a .vscode/launch.json:

{
  "type": "node",
  "request": "attach",
  "name": "Attach NestJS",
  "port": 9229,
  "restart": true,
  "sourceMaps": true
}

6.3 Herramientas para la base de datos

Hay tres opciones para explorar y modificar datos en la base de datos local:

6.4 Inspeccionar colas de trabajo (Bull)

El API utiliza Bull (basado en Redis) para procesar trabajos en segundo plano (emails, imagenes, etc.). Para inspeccionar las colas:

# Conectarse a Redis
docker exec -it nvito-redis redis-cli

# Ver todas las colas de Bull
KEYS bull:*

# Ver trabajos pendientes en una cola
LRANGE bull:<nombre-cola>:wait 0 -1

6.5 Probar uploads de archivos

MinIO funciona como reemplazo local de Cloudflare R2. Los archivos subidos son accesibles via:

• MinIO Console (http://localhost:9001): navegar visualmente por los buckets.
• URL directa: http://localhost:9000/<nombre-bucket>/<ruta-archivo>.

Los buckets nvito-uploads, nvito-assets y nvito-templates tienen politica de acceso publico. El bucket nvito-private requiere autenticacion.

6.6 Ejecutar tests antes de hacer push

Para evitar fallos en el pipeline CI/CD, ejecutar estos comandos antes de cada push:

# En nvito-api
cd ~/desarrollo/Nvito/nvito-api
npm run format          # Auto-corrige formato con Prettier
npm run lint:fix        # Auto-corrige errores de ESLint
npm run lint            # Verifica que no queden errores
npm run test            # Ejecuta tests unitarios

# En nvito-admin y nvito-invitations
npm run lint

6.7 Resetear el entorno completo

Si el entorno local queda en un estado inconsistente, es posible reiniciar todo desde cero:

cd ~/desarrollo/Nvito/nvito-api
npm run dev:reset
# Equivale a: docker:clean -> setup (env:dev -> docker:up -> db:generate -> db:migrate -> db:seed)

Advertencia: Este comando elimina todos los datos de la base de datos, Redis y MinIO. Solo usarlo cuando sea necesario.

API Interactiva (Scalar)

Nvito incluye documentacion interactiva de la API usando Scalar (basada en OpenAPI/Swagger). Esta herramienta permite probar los endpoints directamente desde el navegador.

Como acceder

1. Asegurate de que nvito-api esta corriendo localmente (npm run start:dev)
2. Abre en tu navegador: http://localhost:3000/api/docs
3. La interfaz Scalar te permite:
   • Ver todos los endpoints organizados por modulo
   • Probar requests con datos de ejemplo
   • Ver schemas de request/response
   • Autenticarte con JWT para endpoints protegidos

Autenticacion en Scalar

Para probar endpoints protegidos:

1. Obtener un token JWT de Clerk (desde nvito-admin → DevTools → Application → Cookies)
2. En Scalar, click en "Authorize" → pegar el token como Bearer
3. Ahora puedes hacer requests a endpoints autenticados

Nota: Scalar solo esta disponible en desarrollo local. No se expone en ambientes DEV/TEST/Produccion.

Referencias

• Infraestructura y Ambientes -- Configuracion de ambientes remotos DEV y TEST
• Arquitectura del Sistema -- Arquitectura del sistema
• API Backend -- Documentacion del API backend