Configure Payment Emulator Lab

Índice / Index · Español

Configuration comes from process environment variables. docker-compose.yml supplies safe local defaults and can read a root .env; direct development must set the variables in each process environment.

Which file a process reads is the part that catches people out, because the root .env is the one npm run setup creates and asks you to edit — and it is not read by the servers:

So npm run dev:api with a root .env full of values fails with ADMIN_TOKEN is required: export the variables in that shell, or put them in apps/api/.env. And a NUXT_* value that works in nuxt dev because it sits in apps/console/.env will be silently absent once the same application is built.

Never copy values from a real .env into documentation or commits. The examples below are placeholders or local-only defaults.

#Compose-facing variables

These are the variables a root .env should normally override:

Compose injects internal service URLs itself. Its readable default credentials are for a private development machine only.

#API process

The HTTP API needs no queue at all. Webhook events are committed to PostgreSQL and the worker dispatches them later, through whichever transport WEBHOOK_QUEUE_DRIVER names.

#Worker process

The worker needs the same DATABASE_URL and ADMIN_TOKEN because it boots the shared Nest context for timed transitions.

It also chooses a webhook transport. WEBHOOK_QUEUE_DRIVER takes postgres (the default — the outbox carries its own deliveries and nothing else has to be running), mongo (MONGO_URL, MONGO_DB; a standalone mongod is enough, no replica set) or bullmq (REDIS_URL), which is what docker-compose names.

Allowed hosts are comma-separated hostnames, not URL patterns. The worker also requires http: or https:.

#Console process

Nuxt runtime overrides must use Nuxt's NUXT_ names:

Normal proxied requests use the signed-in person's API session. The admin token remains only as a server-side bootstrap fallback and must never be put under runtimeConfig.public.

Documentation is built from local Markdown and served at /docs/es and /docs/en. It requires no GitHub credentials, public repository URL or published branch. See the documentation portal for publishing and validation.

#Checkout process

Use a different NUXT_SESSION_PASSWORD from the console. The cookies also have different names (emulator_console and emulator_checkout).

#Windows without Docker (run-local.bat)

The launcher reads the root .env and .env.local, then fills in what is missing. Its defaults are not always the code's defaults, because it runs against a PostgreSQL you installed rather than the one Compose publishes:

run-local.bat doctor prints the ports and the chosen transport without changing anything, which is the fastest way to see what these resolved to.

#Script-only variables

All of these except the landing smoke also read ADMIN_TOKEN. The seed and the stack smoke default it to the Compose local default; if Compose is overridden, pass the same value to the script process. setup and admin:create have no such default — they read .env and .env.local, and refuse rather than guess.

#Root commands

setup, admin:create and migrate read .env and then .env.local, and neither file overrides a variable already exported in the shell. The seed, the smokes and the documentation check read only the process environment — see the table at the top.

#Execution modes

#Contract download

Contract import is intentionally separate from runtime:

ALLOW_CONTRACT_DOWNLOAD=true npm run contract:import:mercadopago --workspace @payment-emulator/api

It uses an allow-listed official URL and records a checksum. Do not enable downloads on the API or worker runtime merely to run the emulator. Official snapshots for all three providers are present; see the contract inventory. Their presence does not imply complete runtime schema validation.