Configuración

Todo se configura en dos sitios, y conviene saber cuál es cuál:

El .env del backend — lo que el sistema necesita para arrancar: base de datos, secretos, claves de servicios externos. Se toca con un editor y exige reiniciar.
El panel — lo que cambia el día a día: nombre de la tienda, datos fiscales, formas de pago, proveedor de IA. No exige reiniciar nada.

La regla es sencilla: si es un secreto, va en el .env. Todo lo demás, en el panel. Las claves de API nunca se guardan en la base de datos ni viajan al navegador.

La lista completa de variables, generada del código, está en referencia/variables-entorno.md. Aquí está lo que hace falta entender para decidir.

Lo mínimo para arrancar

Solo una variable es obligatoria:

DATABASE_URL=postgres://usuario:contraseña@localhost:5432/mi_tienda

Sin nada más, el sistema arranca y funciona. Todo lo demás enciende cosas.

Redis: ya no hace falta

La cola de avisos, los flujos de trabajo y las tareas programadas viven en Postgres y sobreviven al reinicio igual. Si REDIS_URL está puesto, el asistente lo enseña como opcional; si no, no avisa de nada. Antes era una pieza más que montar y un aviso falso en la primera pantalla del asistente.

Los secretos de sesión

JWT_SECRET=
COOKIE_SECRET=

Con los de ejemplo puestos, cualquiera que los conozca puede firmarse sus propios tokens y entrar en tu panel. Cámbialos antes de publicar.

En Docker puedes dejarlos vacíos: el contenedor genera unos la primera vez. Solo ponlos a mano si vas a levantar varias réplicas del backend — cada una generaría los suyos y la sesión dejaría de valer al saltar de una a otra.

CORS: quién puede hablar con la tienda

STORE_CORS=https://mitienda.com          # el escaparate
ADMIN_CORS=https://panel.mitienda.com    # el panel
AUTH_CORS=https://panel.mitienda.com

Son listas separadas por comas. Si falta una dirección, el navegador la bloquea y el error no dice que sea culpa de esto: dice «CORS», y se pierde media tarde buscando en el sitio equivocado. Cuando montes un tema nuevo en otro puerto, acuérdate de añadirlo a STORE_CORS.

Lo que enciende cada cosa

Todo lo que sigue es opcional. Sin la variable, la funcionalidad simplemente no está — no falla, no avisa, no estorba.

Correo

SMTP_HOST=
SMTP_PORT=587
SMTP_USER=
SMTP_PASS=
SMTP_FROM=
CONTACT_TO=          # a dónde llega el formulario de contacto

Sin esto no salen ni confirmaciones de pedido ni recuperación de contraseña.

Inteligencia artificial

ANTHROPIC_API_KEY=
OPENAI_API_KEY=
GOOGLE_API_KEY=
MISTRAL_API_KEY=
OPENROUTER_API_KEY=
VOYAGE_API_KEY=      # solo para búsqueda por significado
COHERE_API_KEY=
OLLAMA_URL=http://localhost:11434   # en tu máquina, sin coste

Pones la clave que quieras usar, no todas. El proveedor se elige después en el panel, en la sección IA.

La clave es tuya y el gasto también: el sistema viene con los frenos puestos (tope diario y límite por visitante), pero quien paga las llamadas eres tú. Cómo funciona y qué cuesta: la IA.

Sin ninguna clave la tienda funciona igual — buscador por palabras, fichas, avisos. Lo que necesita clave es lo que escribe o razona.

Pagos en criptomonedas

BTCPAY_URL=
BTCPAY_API_KEY=
BTCPAY_STORE_ID=

Sin BTCPAY_URL el proveedor de pago ni se registra: no aparece en el checkout.

Envíos con Sendcloud

SENDCLOUD_PUBLIC_KEY=
SENDCLOUD_SECRET_KEY=
SENDCLOUD_WEBHOOK_SECRET=    # firma de sus avisos
SENDCLOUD_FROM_...           # dirección de origen, ver el .env.example
SENDCLOUD_FALLBACK_EUR=4.95

Sin SENDCLOUD_PUBLIC_KEY queda el proveedor manual: tarifas planas que configuras tú en el panel.

Temas y extensiones

THEMES_DIR=      # dónde están los temas. Por defecto: themes/
PLUGINS_DIR=     # dónde están los plugins. Por defecto: plugins/
PLUGINS_DISABLED=uno,otro    # apagar uno sin desinstalarlo
LICENSE_PUBLIC_KEY=          # comprobar licencias de plugins de pago

LICENSE_PUBLIC_KEY es pública a propósito: solo sirve para verificar firmas, nunca para crearlas.

Enlaces a la tienda

STOREFRONT_URL=https://mitienda.com
STOREFRONT_RUTA_PRODUCTO=producto     # /producto/<handle>

De aquí salen los enlaces que la IA y los correos mandan al cliente. Si tu tema usa otra ruta —/p/, /articulo/— cámbiala aquí o los enlaces darán 404.

El escaparate se configura aparte

El tema no lee el .env del backend: es otra aplicación, muchas veces en otro servidor. Necesita dos datos suyos:

COMMERCE_URL=https://mitienda.com     # dirección de la tienda
COMMERCE_KEY=pk_...                   # clave publicable del canal de venta

Cada stack los expone a su manera: Vite quiere VITE_, Next quiere NEXT_PUBLIC_ para lo que llegue al navegador. Mira el .env.example del tema.

La clave publicable decide qué productos ve ese escaparate. Es lo que permite que dos tiendas distintas convivan en el mismo backend sin mezclarse los catálogos, así que conviene que cada tema tenga la suya.

Se crea con npm run preparar en el backend, o desde Ajustes en el panel.

Lo que se configura en el panel

Sin tocar ficheros ni reiniciar:

Dónde	Qué
Ajustes	Nombre y marca de la tienda, datos fiscales de las facturas, formas de pago
IA	Proveedor y modelo, tope de gasto diario, qué se puede escribir solo
Temas	Qué tema está activo y su contenido de ejemplo
Extensiones	Plugins instalados y sus ajustes
Usuarios	Quién entra al panel

Los datos fiscales viven en la tienda, no en el código: cambiar un NIF no debería exigir reconstruir nada.