Variables de entorno

Dónde están los ajustes

Crea cada archivo a partir del .env.example que tiene al lado, que documenta todas las variables: cp .env.example .env. Los ejemplos funcionan tal cual para una ejecución local.

Dónde están los ajustes

Un solo archivo, storefront/.env, que se lee al construir la tienda. Todos sus valores son públicos, así que nunca contiene un secreto. Omítelo para usar la tienda de ejemplo; créalo a partir de .env.example cuando conectes una API: cp .env.example .env.

Dónde están los ajustes

Un solo archivo, admin-dashboard/.env, que se lee al construir el panel. Todos sus valores son públicos, así que nunca contiene un secreto. Omítelo para usar la tienda de ejemplo; créalo a partir de .env.example cuando conectes una API: cp .env.example .env.

Dónde están los ajustes

Un solo archivo, back-end/.env, que lee la API con yarn dev, y un contenedor cuando se lo pasas con --env-file .env. Contiene secretos: nunca lo subas al repositorio. Créalo a partir de .env.example, que documenta cada variable y funciona tal cual para una ejecución local: cp .env.example .env.

Lo esencial de la API

La API comprueba JWT_SECRET y CORS_ORIGIN antes de iniciarse. Si falta uno o no se puede usar, se detiene con una línea que indica qué corregir.

Genera tu propio JWT_SECRET con:

node -e "console.log(require('crypto').randomBytes(48).toString('hex'))"

Cualquier credencial de abajo que conserve exactamente su valor de .env.example cuenta como no configurada, así que la función a la que pertenece indica que está desactivada en lugar de fallar en su primera llamada.

Usa MySQL en lugar de SQLite

Crea una base de datos vacía y luego configura el controlador y la conexión en back-end/.env:

DB_TYPE=mysql
DB_HOST=your-mysql-host
DB_PORT=3306
DB_USERNAME=your-mysql-username
DB_PASSWORD=your-mysql-password
DB_DATABASE=your-database-name

Después ejecuta yarn seed para la tienda de demostración, o yarn db:sync para las tablas sin datos. La API en ejecución solo crea y actualiza las tablas por sí misma cuando NODE_ENV=development, así que con NODE_ENV=production uno de esos comandos se ejecuta antes del primer inicio (yarn db:sync:prod o yarn seed:prod después de yarn build).

Tienda y panel de administración

Cada valor NEXT_PUBLIC_* se compila en el JavaScript que carga el navegador, y cualquiera que abra la página puede leerlo. Nunca pongas un secreto en estos archivos, y reconstruye después de cambiar uno.

Las etiquetas de marketing de la tienda también son valores NEXT_PUBLIC_*.

• Analítica y píxeles de seguimiento

Opciones de Docker Compose

No hay que configurar nada para una ejecución local. Para cambiar algo, ponlo en un archivo .env junto a docker-compose.yml y vuelve a ejecutar docker compose up --build: los frontends compilan estos valores dentro.

El contenedor de la API también lee back-end/.env cuando existe, así que las claves de pagos, archivos multimedia e IA se configuran en un solo lugar para yarn dev y para Docker. El archivo compose manda en los pocos valores que cambian dentro de un contenedor: la ruta de la base de datos, el puerto, NODE_ENV=production, CORS_ORIGIN y FRONTEND_URL. Los datos se guardan en el volumen ecommerce-data.

Almacenamiento multimedia

Las fotos de productos, las imágenes de categorías, los avatares, los adjuntos del chat, los resultados del estudio de IA y las fotos del probador se suben a un bucket de Cloudflare R2, o a cualquiera compatible con S3. Configura las cinco variables en back-end/.env y da a ambos frontends el host público del bucket mediante NEXT_PUBLIC_MEDIA_HOSTNAME (con Docker Compose, MEDIA_HOSTNAME).

R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET_NAME=
R2_PUBLIC_URL=https://your-public-url.r2.dev

Sin un bucket, yarn seed guarda cada imagen de producto y de categoría como una ruta /mock-media/…, y ambos frontends incluyen esos 35 archivos en public/mock-media/, así que el catálogo se muestra sin subir nada. Solo deja de funcionar la subida de imágenes nuevas: responde 503 hasta que se configure el bucket.

Con un bucket, la carga de datos sube allí las imágenes de su catálogo. Conserva public/mock-media/ en ambos frontends mientras algún producto siga apuntando a ella.

Pagos con tarjeta

Los pagos con tarjeta funcionan con Stripe: STRIPE_SECRET_KEY y STRIPE_WEBHOOK_SECRET en back-end/.env, y NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY para la tienda. Sin ellas no se cobra ningún pago con tarjeta, y el pago contra reembolso funciona con normalidad.

STRIPE_SECRET_KEY=sk_test_your-stripe-secret-key
STRIPE_WEBHOOK_SECRET=whsec_your-webhook-secret

• Configura Stripe

Correo electrónico

La plantilla no incluye ningún sistema de envío de correo, así que nunca se envía ningún mensaje por correo. Fuera de producción, el token de restablecimiento de contraseña de un cliente se escribe en su lugar en el registro de la API; con NODE_ENV=production no va a ningún sitio. Conecta tu propio proveedor de correo antes de pasar a producción: el punto de conexión es forgotPassword en back-end/src/modules/customer-auth/customer-auth.controller.ts.

• Cuentas de cliente

Funciones de IA

La tienda de ejemplo en los frontends

Ambos frontends funcionan sin API. Si se inician o se construyen sin NEXT_PUBLIC_API_BASE_URL, cada uno responde a todas las solicitudes desde una tienda de ejemplo en el navegador y muestra un aviso "Sample data". Configurar la dirección es lo que la desactiva.

• Cualquier correo y contraseña inician sesión como el comprador de ejemplo en la tienda. En el panel, cualquier correo válido con una contraseña de al menos 6 caracteres inicia sesión como Super Admin.
• Los cambios son reales y se guardan en el almacenamiento del navegador, así que sobreviven a una recarga. Para empezar de cero, ejecuta localStorage.removeItem("mock_db_v1"); location.reload(); en la consola del navegador.
• El pago en la tienda se completa sin llamar a Stripe.
• En el panel, el asistente de IA y el estudio de IA no están disponibles, porque ambos necesitan las claves de la API.
• Cuando tu API esté en producción, yarn remove:mock en cualquiera de las dos aplicaciones elimina la tienda de ejemplo y su aviso. Deja public/mock-media/ en su sitio, porque un backend cargado sin bucket apunta allí sus imágenes.

Cómo funciona la tienda de ejemplo

Modo demostración

Pasar a producción

Antes de desplegar en cualquier sitio público:

1. Configura NODE_ENV=production y un JWT_SECRET largo y aleatorio propio en back-end/.env.
2. Pon en CORS_ORIGIN las direcciones de tu tienda y de tu panel, separadas por comas, y en FRONTEND_URL la dirección del panel.
3. Con una base de datos vacía, ejecuta yarn build, luego yarn db:sync:prod una vez (o yarn seed:prod para la tienda de demostración), y después yarn start:prod.
4. Apunta la comprobación de estado de tu proveedor de alojamiento a /api/health.
5. Construye cada frontend con NEXT_PUBLIC_API_BASE_URL apuntando a tu API desplegada y con NEXT_PUBLIC_SITE_URL de la tienda apuntando a su propia dirección.
6. Cambia la contraseña del Super Admin, o empieza con tablas vacías.