Traducción de
docs/en/operations/configuration.md, que es el original. Si discrepan, manda el inglés.
La configuración viene de variables de entorno del proceso. docker-compose.yml
trae valores locales seguros y puede leer un .env de la raíz; en desarrollo
directo hay que ponerlas en el entorno de cada proceso.
Qué fichero lee cada proceso es la parte que pilla a todo el mundo, porque el
.env de la raíz es el que crea npm run setup y el que te pide editar — y no
lo leen los servidores:
| Quién lee | Qué lee |
|---|---|
docker-compose.yml |
El .env de la raíz, y sólo para los tres nombres que sustituye (ADMIN_TOKEN, SESSION_PASSWORD, CHECKOUT_SESSION_PASSWORD) |
setup, migrate, admin:create, run-local.bat |
El .env de la raíz y después .env.local. Ninguno pisa una variable ya exportada en la terminal |
seed, smoke, smoke:stack, smoke:landing, docs:check |
Sólo el entorno del proceso |
| API y worker | El .env del directorio de trabajo, que con los scripts del workspace es apps/api/.env — nunca el de la raíz |
| Consola y checkout | apps/<app>/.env sólo en nuxt dev. El servidor compilado (node .output/server/index.mjs, y por tanto Compose) lee sólo el entorno del proceso |
Por eso npm run dev:api con el .env de la raíz lleno falla con ADMIN_TOKEN is required: exporta las variables en esa terminal o ponlas en apps/api/.env. Y
un valor NUXT_* que funciona en nuxt dev porque está en apps/console/.env
desaparecerá sin avisar en cuanto esa misma aplicación se compile.
Nunca copies valores de un .env real a la documentación ni a un commit. Los
ejemplos de abajo son marcadores o valores que sólo sirven en local.
#Variables de cara a Compose
Son las que un .env de la raíz normalmente debería pisar:
| Variable | ¿Obligatoria? | Para qué | Ejemplo seguro |
|---|---|---|---|
ADMIN_TOKEN |
Sí, fuera de los valores de Compose | Credencial raíz de arranque y de CI; mínimo 16 caracteres | cámbialo-por-hex-aleatorio |
SESSION_PASSWORD |
Recomendada | Sella la cookie de la consola en Compose | cámbialo-por-32-o-más-caracteres |
CHECKOUT_SESSION_PASSWORD |
Recomendada | Sella la cookie aparte del checkout | otros-32-o-más-caracteres-distintos |
Compose inyecta él mismo las URLs internas de los servicios. Sus credenciales legibles por defecto son para una máquina de desarrollo privada y nada más.
#Proceso de la API
| Variable | ¿Obligatoria? | Por defecto | Para qué |
|---|---|---|---|
ADMIN_TOKEN |
Sí | ninguno | Credencial de arranque; la API no arranca si falta o es corta |
PORT |
No | 8080 |
Puerto HTTP |
DATABASE_URL |
No | PostgreSQL local en 54329 |
Conexión de MikroORM |
MIKRO_ORM_DEBUG |
No | false |
Salida de depuración del ORM cuando vale exactamente true |
DEFAULT_SITE_ID |
No | MLA |
Mapeo de sitio y moneda por defecto de Mercado Pago |
API_PUBLIC_URL |
No | http://localhost:8080 |
Origen público de los recursos PayPal y del certificado de webhooks |
CHECKOUT_PUBLIC_URL |
No | http://localhost:3001 |
Origen de las redirecciones de Stripe y la aprobación de PayPal |
ALLOW_CONTRACT_DOWNLOAD |
No | false |
Interruptor explícito del importador de contratos |
MERCADOPAGO_CONTRACT_URL |
No | URL oficial permitida de GitHub | Sobrescribe la fuente dentro de las reglas del importador |
La API HTTP no necesita cola ninguna. Los eventos de webhook se confirman en
PostgreSQL y el worker los despacha después, por el transporte que nombre
WEBHOOK_QUEUE_DRIVER.
#Proceso del worker
El worker necesita el mismo DATABASE_URL y ADMIN_TOKEN, porque levanta el
contexto Nest compartido para las transiciones por reloj.
Además elige un transporte de webhooks. WEBHOOK_QUEUE_DRIVER acepta postgres
(el valor por defecto — el outbox lleva sus propias entregas y no hace falta nada
más en marcha), mongo (MONGO_URL, MONGO_DB; basta un mongod suelto, sin
replica set) o bullmq (REDIS_URL), que es el que nombra docker-compose.
| Variable | ¿Obligatoria? | Por defecto | Para qué |
|---|---|---|---|
WEBHOOK_QUEUE_DRIVER |
No | postgres |
postgres, mongo o bullmq |
REDIS_URL |
Para bullmq |
redis://localhost:6389 |
Conexión de BullMQ. run-local.bat la deriva de REDIS_PORT, para que el puerto que comprueba y el que marca el worker no puedan discrepar |
MONGO_URL |
Para mongo |
mongodb://localhost:27017 |
Un mongod suelto basta |
MONGO_DB |
No | payment_emulator |
La base que guarda webhook_jobs |
RUNTIME_OUTBOUND_ENABLED |
Para entregar | false |
Tiene que valer true antes de que se permita HTTP saliente |
WEBHOOK_ALLOWED_HOSTS |
No | localhost,127.0.0.1,host.docker.internal |
Excepciones: hosts permitidos a pesar de resolver a una direccion interna. Un dominio publico no necesita estar aqui |
OUTBOX_INTERVAL_MS |
No | 1000 |
Intervalo de sondeo del outbox |
TIMED_INTERVAL_MS |
No | 1000 |
Intervalo de las transiciones por reloj |
SETTLEMENT_INTERVAL_MS |
No | 60000 |
Intervalo del barrido de liberación de reserva |
Los hosts permitidos son nombres separados por comas, no patrones de URL. El
worker exige además http: o https:.
#Proceso de la consola
Lo que pise Nuxt en ejecución tiene que usar los nombres NUXT_:
| Variable | ¿Obligatoria? | Por defecto | Exposición |
|---|---|---|---|
NUXT_API_URL |
No | http://localhost:8080 |
Sólo servidor; origen de NestJS |
NUXT_ADMIN_TOKEN |
Necesaria para el respaldo de arranque | vacío | Sólo servidor; token del operador raíz |
NUXT_SESSION_PASSWORD |
Sí | vacío | Sólo servidor; secreto de la cookie, 32+ caracteres |
NUXT_PUBLIC_CHECKOUT_URL |
No | http://localhost:3001 |
Visible en el navegador |
NUXT_PUBLIC_API_PUBLIC_URL |
No | http://localhost:8080 |
Visible en el navegador, para las instrucciones de integración |
NUXT_PUBLIC_SITE_URL |
No | vacío | Origen público del despliegue. Fija la URL canónica, las alternativas hreflang, la imagen de Open Graph y las direcciones de robots.txt y sitemap.xml. Vacío, cada petición responde por su propio host, que es lo que necesita una instalación local |
Las peticiones normales van con la sesión de API de la persona que entró. El
token de administrador queda sólo como respaldo de arranque en el servidor y
nunca debe ponerse bajo runtimeConfig.public.
La documentación se construye desde Markdown local y se sirve en /docs/es y /docs/en.
No necesita credenciales de GitHub, URL pública del repositorio ni rama publicada.
Consulta el portal de documentación para publicación y validación.
#Proceso del checkout
| Variable | ¿Obligatoria? | Por defecto | Exposición |
|---|---|---|---|
NUXT_API_URL |
No | http://localhost:8080 |
Sólo servidor |
NUXT_SESSION_PASSWORD |
Sí | vacío | Sólo servidor; secreto de la cookie, 32+ caracteres |
Usa un NUXT_SESSION_PASSWORD distinto del de la consola. Las cookies además
se llaman distinto (emulator_console y emulator_checkout).
#Windows sin Docker (run-local.bat)
El lanzador lee el .env de la raíz y .env.local, y después rellena lo que
falte. Sus valores por defecto no siempre son los del código, porque corre contra
un PostgreSQL que instalaste tú y no contra el que publica Compose:
| Variable | Por defecto en run-local.bat |
Para qué |
|---|---|---|
PG_PORT |
se descubre y se escribe en .env.local |
El puerto en el que responde el PostgreSQL local |
PG_CANDIDATES |
5432 5433 5434 5435 54329 |
Los puertos que prueba setup; gana la instancia más nueva |
PGSUPERUSER / PGSUPERPASSWORD |
postgres / postgres |
Sólo los usa setup, para crear el rol payment y la base |
DATABASE_URL |
postgresql://payment:payment@localhost:5432/payment_emulator |
El puerto local, no el 54329 que publica Compose. El puerto que lleve esta URL manda sobre PG_PORT |
API_PORT |
8080 |
Fija también API_URL; un PORT del entorno se lee aquí |
CONSOLE_PORT / CHECKOUT_PORT |
3000 / 3001 |
Fijan también CONSOLE_URL y CHECKOUT_URL |
REDIS_PORT |
6379 |
El de una instalación local, no el 6389 que publica Compose. REDIS_URL se deriva de él |
MONGO_PORT |
27017 |
MONGO_URL se deriva de él |
WEBHOOK_ALLOWED_HOSTS |
localhost,127.0.0.1 |
Sin host.docker.internal: aquí no hay contenedor al que volver |
ADMIN_TOKEN |
el token de desarrollo de Compose | La API no arranca sin uno, así que lo pone el lanzador |
NUXT_SESSION_PASSWORD / CHECKOUT_SESSION_PASSWORD |
los secretos de desarrollo de Compose | Valores distintos para cada superficie |
run-local.bat doctor imprime los puertos y el transporte elegido sin tocar
nada, que es la forma más rápida de ver en qué quedó todo esto.
#Variables sólo de scripts
| Variable | Script | Por defecto |
|---|---|---|
API_URL |
instalación, creación de administradora, semilla y humareda de pila | http://localhost:8080 |
ADMIN_EMAIL |
creación de administradora | se pregunta |
ADMIN_PASSWORD |
creación de administradora | se pregunta |
ADMIN_NAME |
creación de administradora | lo que va antes de @ |
CONSOLE_URL |
humareda de pila y de la landing | http://localhost:3000 |
CHECKOUT_URL |
humareda de pila | http://localhost:3001 |
SMOKE_EMAIL |
humareda de pila | smoke-operator@example.test |
SMOKE_PASSWORD |
humareda de pila | smoke-operator-password |
SEED_ADMIN_EMAIL |
semilla | operadora@example.test |
SEED_PASSWORD |
semilla | emulator-demo-password |
Todos ellos menos la humareda de la landing leen además ADMIN_TOKEN. La semilla
y la humareda de pila lo hacen coincidir por defecto con el de Compose; si pisas
los de Compose, pásale el mismo valor al proceso del script. setup y
admin:create no tienen ese valor por defecto: leen .env y .env.local, y se
niegan antes que adivinar.
#Comandos de la raíz
| Comando | Hace |
|---|---|
npm run setup |
La instalación limpia: dependencias, compilado, base, migraciones y administradora. --docker/--local, --seed, --reset, --no-admin, --yes |
npm run admin:create |
Una administradora, por POST /auth/bootstrap, contra una API viva |
npm run migrate |
Las migraciones pendientes. -- --down para deshacer una, -- --fresh para todas y de vuelta |
npm run seed |
Los datos de demostración, por las superficies HTTP |
npm run smoke / npm run smoke:stack |
La humareda sin servidor, y la que va contra la pila en marcha |
npm run smoke:landing |
La página pública contra una consola viva: canónica, hreflang, datos estructurados, robots.txt, sitemap.xml, el 404 y el noindex de todo lo que hay tras el login. La apunta CONSOLE_URL |
npm run docs:check |
Los enlaces locales y las contrapartes inglés/español |
setup, admin:create y migrate leen .env y después .env.local, y ninguno
de los dos ficheros pisa una variable ya exportada en la terminal. La semilla, las
humaredas y la comprobación de documentación leen sólo el entorno del proceso
—ver la tabla del principio—.
#Modos de ejecución
| Modo | Procesos | Uso previsto |
|---|---|---|
| Compose completo | PostgreSQL, Redis, API, worker, consola, checkout | Entrada al proyecto y aceptación, recomendado; ahí el worker va fijado a bullmq |
run-local.bat |
Los cuatro procesos contra un PostgreSQL instalado | Windows sin Docker; lee .env.local para los ajustes de la máquina |
run.bat |
Compose, envuelto | Windows con Docker; up, dev, infra, setup, admin, reset y el resto |
| Desarrollo directo | Dependencias en Compose; cuatro procesos npm | Iteración rápida |
| Sólo API | PostgreSQL + API | Trabajo de proveedor o plano de control sin entrega de webhooks |
| Comprobaciones | Typecheck, lint, Vitest, build, humareda pura | Verificación local y de CI |
#Descarga de contratos
Importar un contrato está separado del runtime a propósito:
ALLOW_CONTRACT_DOWNLOAD=true npm run contract:import:mercadopago --workspace @payment-emulator/api
Usa una URL oficial permitida y anota una suma de comprobación. No habilites las descargas en el runtime de la API o del worker sólo para correr el emulador. Hay instantáneas oficiales de las tres pasarelas: véase el inventario de contratos. Su presencia no implica validación completa del esquema en el runtime.