Variables de Entorno y Setup Local

Requisitos previos

Node.js 22+
Yarn 1.x (o npm)
MySQL 8+
Variables de entorno configuradas (ver abajo)

Arranque rapido

# 1. Clonar el repositorio
git clone <repo-url> BoostAPI
cd BoostAPI

# 2. Instalar dependencias
yarn install

# 3. Copiar archivo de entorno
cp .env.template .env

# 4. Editar .env con tu configuracion local
#    (ver tabla de variables abajo)

# 5. Levantar en modo desarrollo (hot reload)
yarn start:dev

# 6. Abrir Swagger
open http://localhost:3003/api

Seed de datos para desarrollo

# Suite base completa (usuarios, empleados, RBAC, campos personalizados)
yarn seed:dev:all

# Seeds individuales
yarn seed:dev:users
yarn seed:dev:employees
yarn seed:dev:rbac
yarn seed:dev:catalog
yarn seed:dev:custom-fields
yarn seed:dev:web-contact-assignment

# Seed personal para desarrollo local
yarn seed:local:rolando

Variables de entorno – Referencia completa

Runtime

Variable	Requerida	Descripcion	Ejemplo
`NODE_ENV`	Si	Entorno de Node	`development`
`BOOST_RUNTIME_MODE`	No	Modo de runtime Boost	`dev`
`APP_RUNTIME_MODE`	No	Modo de la app	`dev` / `preview` / `prod`
`HOST`	No	Host de binding	`0.0.0.0`
`PORT`	No	Puerto del servidor	`3000` (default)

Base de datos (MySQL)

Variable	Requerida	Descripcion	Ejemplo
`DB_HOST`	Si	Host de MySQL	`localhost`
`DB_PORT`	Si	Puerto de MySQL	`3306`
`DB_USERNAME`	Si	Usuario de MySQL	`root`
`DB_PASSWORD`	Si	Password de MySQL	`password`
`DB_NAME`	Si	Nombre de la base de datos	`boost_crm`

Autenticacion

Variable	Requerida	Descripcion	Ejemplo
`JWT_SECRET`	Si	Secreto para firmar JWTs	Cadena aleatoria segura
`AUTH_ALLOW_FIRST_LOGIN_PASSWORD_BOOTSTRAP`	No	Permitir bootstrap de password	`true` (solo durante rollout)

CORS

Variable	Requerida	Descripcion	Ejemplo
`CORS_ALLOWED_ORIGINS`	No	Origenes permitidos (CSV)	`http://localhost:3000,http://localhost:3001`

Siempre permitidos: https://app.boost.com.gt, https://boost-v2-eight.vercel.app. En dev tambien se permite localhost en cualquier puerto.

AWS / Media

Variable	Requerida	Descripcion
`AWS_S3_BUCKET`	Si	Nombre del bucket S3
`AWS_ACCES_KEY_ID_AOC`	Si	Access key ID de AWS
`AWS_SECRET_ACCESS_KEY_AOC`	Si	Secret access key de AWS
`AWS_REGION`	No	Region AWS (default: `us-east-1`)
`MEDIA_PUBLIC_BASE_URL`	Si	URL base para media publica
`MEDIA_WORKER_POLL_MS`	No	Intervalo de polling del worker (ms)
`MEDIA_INLINE_WORKER_ENABLED`	No	Procesar media inline
`MEDIA_INLINE_WORKER_RECOVER_ON_BOOT`	No	Recuperar uploads pendientes al arrancar

Zauru

Variable	Requerida	Descripcion
`ZAURU_ENV`	Si	Entorno Zauru: `dev` / `preview` / `prod`
`ZAURU_APP_BASE_URL_DEV`	Si	URL Zauru dev: `https://zauru.herokuapp.com`
`ZAURU_APP_BASE_URL_PROD`	Si	URL Zauru prod: `https://app.zauru.com`
`ZAURU_SESSION_ENCRYPTION_KEY`	Si	Clave AES-256 para cifrar sesiones
`ZAURU_SESSION_REFRESH_SKEW_SECONDS`	No	Segundos de margen para refresh (default: 300)
`ZAURU_CATALOG_CACHE_TTL_DAYS`	No	TTL de cache de catalogo en dias (default: 7)
`ZAURU_PAYEE_GENERAL_INFO_CACHE_TTL_MINUTES`	No	TTL cache de info general de payee
`ZAURU_MEDIA_BASE_URL_APP`	Si	Base URL de Cloudinary para imagenes

Pulpito (Cache)

Variable	Requerida	Descripcion	Default
`PULPITO_CATALOG_ENABLED`	No	Habilitar cache de catalogo	`true`
`PULPITO_L1_MAX_MEMORY_MB`	No	Max memoria del cache L1	`100`
`PULPITO_L1_MAX_ENTRIES`	No	Max entradas en cache	`5000`
`PULPITO_MAX_BG_REFRESHES`	No	Max refreshes en background	`10`
`PULPITO_MAX_CONCURRENT_FETCHES`	No	Max fetches concurrentes	`20`
`PULPITO_QUERY_TIMEOUT_MS`	No	Timeout de query (ms)	`8000`

Catalogo

Variable	Requerida	Descripcion	Default
`CATALOGO_DEFAULT_PAGE_SIZE`	No	Items por pagina	`20`
`CATALOGO_INTERNAL_CACHE_TTL_SECONDS`	No	TTL cache interno	`60`

Communications (Interacciones)

Variable	Requerida	Descripcion
`COMMUNICATIONS_BASE_URL`	Si*	URL del servicio de Communications
`COMMUNICATIONS_API_KEY`	Si*	API key de Communications
`COMMUNICATIONS_PRIVILEGED_OPERATOR_EMAILS`	No	Emails de operadores privilegiados
`COMMUNICATIONS_ENTITY_ID_HARD`	No	Override de entity ID
`COMMUNICATIONS_AUTO_LOGIN_ON_AUTH`	No	Auto-login en Communications al autenticar
`COMMUNICATIONS_DEV_TUNNEL_ENABLED`	No	Tunnel de dev para webhooks
`COMMUNICATIONS_DEV_WEBHOOK_RESYNC_ENABLED`	No	Re-sync webhook en dev
`COMMUNICATIONS_BOOT_WEBHOOK_RESYNC_ENABLED`	No	Re-sync webhook al arrancar
`COMMUNICATIONS_USER_WEBHOOK_RESYNC_ENABLED`	No	Re-sync en login/cambio de entidad

*Solo requerido si se usan interacciones de mensajeria.

URLs publicas

Variable	Requerida	Descripcion
`BOOST_PUBLIC_BASE_URL`	No	URL publica del backend (auto-detecta desde RENDER_EXTERNAL_URL)
`RENDER_EXTERNAL_URL`	No	URL externa de Render (auto-inyectada por Render)
`DISCOGUA_QUOTE_PAYMENT_URL`	No	URL base para links de pago de cotizaciones

Modos de runtime

Modo	Descripcion	Zauru
`dev`	Desarrollo local. CORS permisivo en localhost	`zauru.herokuapp.com`
`preview`	Prod-like pero con datos de staging	`zauru.herokuapp.com` (forzado)
`prod`	Produccion real	`app.zauru.com`

Regla clave: Si NODE_ENV=preview, BoostAPI fuerza entorno Zauru de preview (Heroku) aunque ZAURU_ENV=prod.

Scripts utiles

Script	Descripcion
`yarn start:dev`	Desarrollo con hot-reload
`yarn start:prod`	Produccion (desde `dist/`)
`yarn build`	Compilar TypeScript
`yarn build:render`	Build para Render (fuerza devDependencies)
`yarn lint`	Correr ESLint
`yarn test`	Correr tests
`yarn test:cov`	Tests con cobertura
`yarn seed:dev:all`	Seed completa de desarrollo
`yarn media:worker`	Worker de procesamiento de media
`yarn interactions:worker`	Worker de procesamiento de interacciones

Referencia privada: Ver BoostAPI/docs/local-development-and-seeds.md para guia detallada de seeds y BoostAPI/.env.template para la plantilla completa con comentarios.