Solución de problemas

Docker no se está ejecutando

failed to connect to the docker API at unix:///…/docker.sock; check if the path is correct and if the daemon is running

Las versiones antiguas de Docker muestran "Cannot connect to the Docker daemon" en su lugar. En ambos casos, el motor de Docker no está iniciado.

1. 01

   Abre Docker Desktop

   Inicia Docker Desktop y espera a que indique que el motor está en ejecución. En Linux, inicia el servicio: sudo systemctl start docker.
2. 02

   Comprueba que Docker responde

   TerminalCopiar

   docker info

   Resultado esperado: Muestra una sección Server en lugar de un error.
3. 03

   Vuelve a ejecutar tu comando de inicio

   docker compose up --build para el paquete Full Stack, o tus comandos docker build y docker run para una sola aplicación.

Un puerto ya está en uso

ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
Error: listen EADDRINUSE: address already in use :::3030

La primera línea viene de Docker, la segunda de yarn dev. Otro programa ya escucha en 3030, 3031 u 8000: a menudo una ejecución anterior de la tienda o el servidor de desarrollo de otro proyecto.

1. 01

   Averigua qué ocupa el puerto

   En macOS o Linux:

   TerminalCopiar

   lsof -i :3030

   En Windows, en PowerShell:

   TerminalCopiar

   netstat -ano | findstr :3030
2. 02

   Detenlo

   Cierra ese programa o detén la ejecución anterior: Ctrl+C en su terminal, docker compose down en su carpeta, o docker stop para un contenedor que iniciaste con docker run. Después vuelve a iniciar la tienda.
3. 03

   O ejecuta la tienda en otros puertos

   Con el Full Stack en Docker, crea un archivo llamado .env en la carpeta e-commerce-1, junto a docker-compose.yml, con el puerto que necesitas. SITE_PORT mueve la tienda, ADMIN_PORT el panel y API_PORT la API; las direcciones que usan las aplicaciones lo siguen solas.

   e-commerce-1/.envCopiar

   ADMIN_PORT=3041

   Después ejecuta el mismo comando otra vez. Tras un arranque fallido, continúa donde se detuvo:

   Terminalen e-commerce-1Copiar

   docker compose up --build

   Resultado esperado: La aplicación responde en su nuevo puerto, aquí localhost:3041Local.

La construcción de Docker falla

La primera construcción descarga las imágenes base y todas las dependencias, y luego construye las imágenes. Si algo lo impide, se detiene con "failed to solve" y el paso que falló.

• Sin conexión o tiempo de espera agotado: la construcción necesita acceso a internet. Vuelve a ejecutar el comando cuando tengas conexión; los pasos terminados quedan en caché.
• No space left on device: libera espacio en Docker Desktop o revisa cuánto usa Docker con docker system df.
• Falla siempre en el mismo paso: vuelve a construir sin la caché y luego inicia.

docker compose build --no-cache
docker compose up

En un paquete de una sola aplicación, añade --no-cache a tu comando docker build.

Un primer inicio que parece bloqueado suele estar todavía cargando la tienda de demostración. La tienda y el panel de administración solo se inician cuando la API informa de que está en buen estado.

Yarn dice que su versión es 1.22

This project's package.json defines "packageManager": "yarn@4…". However the current global version of Yarn is 1.22…

Cada aplicación fija Yarn 4 a través de Corepack. Este mensaje significa que Corepack aún no está habilitado, así que respondió en su lugar el Yarn global antiguo.

corepack enable

Después vuelve a ejecutar yarn install. Si tu Node.js no trae Corepack, instálalo antes con npm install -g corepack.

La API se detiene antes de iniciarse

✖ The API cannot start: JWT_SECRET is not set. Set it in back-end/.env to the output of: …
✖ The API cannot start: JWT_SECRET is still the example value from .env.example, …
✖ The API cannot start: CORS_ORIGIN is not set. List the storefront and admin dashboard origins, …

La API revisa sus ajustes antes de iniciarse y muestra una línea por cada problema. Las causas:

• No hay archivo `.env`, o `JWT_SECRET` está vacío. Crea el archivo en back-end/ con cp .env.example .env.
• `JWT_SECRET` sigue siendo el valor de ejemplo con `NODE_ENV=production`. Cualquiera podría firmar un token con el ejemplo público, así que un inicio en producción lo rechaza. Genera tu propio secreto.
• `CORS_ORIGIN` está vacío con `NODE_ENV=production`. Indica las direcciones de la tienda y del panel, separadas por comas.

Genera un secreto con:

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

Con Docker no necesitas uno: un contenedor sin un JWT_SECRET propio, o con el de ejemplo, genera un secreto y lo guarda en el volumen de datos.

• Lo esencial de la API

La comprobación de estado responde 503

{"status":"unavailable"}
The database has no tables yet. Run `yarn seed` in back-end/, then restart the API.

/api/health responde 503 hasta que la base de datos responde y contiene sus tablas. La segunda línea es lo que dice el registro de la API al arrancar cuando faltan las tablas.

• Sin Docker, en desarrollo: ejecuta yarn seed en back-end/ (tablas y tienda de demostración), o yarn db:sync (solo tablas), y luego reinicia la API.
• Con `NODE_ENV=production`: la API no crea tablas al iniciarse. Ejecuta una vez yarn db:sync:prod (tablas vacías) o yarn seed:prod (con la tienda de demostración), después de yarn build.
• Con Docker sobre SQLite: el contenedor crea la base de datos por sí solo en el primer inicio. Con MySQL no lo hace: ejecuta tú mismo una vez el comando de esquema o de carga de datos.
• "The database has no accounts, so nobody can sign in" significa que las tablas existen pero nunca se añadió ninguna cuenta: ejecuta yarn seed en back-end/.

MySQL no arranca o no carga los datos

La API crea sus tablas en una base de datos que ya existe; no crea la base de datos por sí misma. Crea primero una base de datos vacía, pon su nombre en DB_DATABASE en back-end/.env y luego ejecuta yarn seed (o yarn db:sync para las tablas sin la tienda de demostración).

• Revisa los cinco valores de conexión DB_* y que DB_TYPE=mysql.
• Con NODE_ENV=production la API en ejecución nunca crea tablas, así que uno de esos comandos tiene que ejecutarse antes del primer inicio.

• Usa MySQL en lugar de SQLite

El inicio de sesión falla

• Revisa la cuenta y la aplicación. Las cuentas de personal inician sesión en el panel en el puerto 3031: admin@example.com con Admin@123. Los clientes inician sesión en la tienda en el puerto 3030: john.doe@example.com con password123.
• Revisa el registro de la API. "The database has no accounts, so nobody can sign in" significa que nunca se añadió la tienda de demostración. Sin Docker, ejecuta yarn seed en back-end/. Con Docker, el volumen se creó con SEED_DEMO_DATA=false.
• "The database has no tables yet" significa que el esquema nunca se creó: ejecuta yarn seed en back-end/ y reinicia la API.
• Cambiaste la contraseña del Super Admin y ya no la tienes: empieza de cero con datos de demostración nuevos, más abajo.
• "That email and password combination didn't work. Please try again." es la misma respuesta para un correo sin cuenta y para una contraseña incorrecta, así que revisa ambos.
• "Too many attempts. Wait a minute and try again." significa que una dirección hizo más de 10 intentos en una ruta de inicio de sesión o de contraseña en un minuto. Espera un minuto y vuelve a intentarlo.

El inicio de sesión falla

• Revisa el registro de la API. "The database has no accounts, so nobody can sign in" significa que nunca se añadió la tienda de demostración: ejecuta yarn seed, o inicia el contenedor de Docker con -e SEED_DEMO_DATA=true en un volumen nuevo.
• "The database has no tables yet" significa que el esquema nunca se creó: ejecuta yarn seed y reinicia la API.
• Revisa la cuenta y la ruta. El personal inicia sesión en POST /api/auth/login (el Super Admin es admin@example.com con Admin@123); los clientes en POST /api/auth/customer/login (john.doe@example.com con password123). Un inicio de sesión fallido responde 401 con el mismo mensaje tanto si el correo como si la contraseña son incorrectos.
• Una respuesta `429` significa que una dirección hizo más de 10 intentos en una ruta de inicio de sesión, registro, contraseña o seguimiento de pedidos en un minuto. La cabecera Retry-After indica cuántos segundos esperar.

El inicio de sesión falla

Con la tienda de ejemplo, cualquier correo y contraseña te inician sesión en la tienda, y cualquier correo válido con una contraseña de al menos 6 caracteres en el panel. Cuando conectes una API, inicia sesión con una cuenta que exista en ella: el Super Admin de demostración es admin@example.com con Admin@123, y el cliente de demostración john.doe@example.com con password123.

Todos los visitantes reciben "Too many attempts" detrás de un proxy

El inicio de sesión, el registro, el restablecimiento de contraseña y el seguimiento de pedidos como invitado permiten 10 solicitudes por minuto por dirección y ruta, y después responden 429. El probador también cuenta por dirección. La API busca la dirección del visitante en X-Forwarded-For solo cuando la solicitud llega de un proxy con una dirección privada, de loopback o de la plataforma, como en Railway o detrás de Caddy o nginx en la misma máquina.

Cuando tu proxy llega a la API desde una dirección pública, todos los visitantes parecen ese único proxy y comparten un solo cupo. Indica a la API cuántos proxies hay delante de ella:

TRUST_PROXY=1

TRUST_PROXY=false nunca lee la cabecera. Déjalo sin configurar cuando se accede a la API directamente o a través de un proxy con una dirección privada. Los recuentos se guardan en la memoria de la API, así que un reinicio los borra.

Aparece un aviso "Sample data"

El frontend funciona con su tienda de ejemplo integrada en lugar de la API, porque se inició o se construyó sin NEXT_PUBLIC_API_BASE_URL. Lo que cambies se guarda entonces en el navegador, no en la base de datos, y no se cobra ningún pedido.

1. 01

   Da al frontend la dirección de la API

   Crea el .env del frontend a partir de .env.example si no tiene uno. NEXT_PUBLIC_API_BASE_URL debe ser la dirección de la API incluyendo /api, por ejemplo http://localhost:8000/api.
2. 02

   Comprueba que la API responde

   Abre localhost:8000/api/healthLocal. Debe responder {"status":"ok"}. Si la dirección está configurada pero la API no responde, las páginas no pueden cargar sus datos: la tienda de ejemplo no la sustituye.
3. 03

   Reinicia o reconstruye el frontend

   La dirección se compila dentro. Reinicia yarn dev después de cambiarla, vuelve a ejecutar yarn build antes de yarn start, o con Docker vuelve a ejecutar docker compose up --build.

Un cambio en el .env de un frontend no tiene efecto

Cada valor NEXT_PUBLIC_* se compila en el JavaScript que carga el navegador cuando se construye la aplicación. Cambiar el archivo no cambia nada hasta que la aplicación se vuelve a construir.

Una función indica que no está configurada

Los pagos con tarjeta, las subidas, el asistente de IA, el estudio de IA, la eliminación de fondo y el probador solo se activan cuando sus claves están en back-end/.env. El probador, el estudio y la eliminación de fondo también necesitan el bucket de archivos multimedia. Una clave que conserva exactamente su valor de .env.example cuenta como no configurada, así que un .env.example copiado arranca sin problemas y cada una de esas funciones indica que está desactivada en lugar de fallar en su primera llamada.

• Pega tu clave real encima del valor de ejemplo, no a su lado.
• Reinicia la API después de cambiar back-end/.env. Con Docker Compose la API también lee ese archivo, así que basta con volver a ejecutar docker compose up; un contenedor de API independiente necesita --env-file .env en su docker run.

• Variables de entorno

Las subidas responden 503

File uploads are not set up yet. Add the R2 storage settings to the server's .env file to enable them.

Cada subida desde el panel (fotos de productos, avatares, adjuntos del chat, los resultados del estudio de IA) va a un bucket de Cloudflare R2 u otro compatible con S3, y responde 503 hasta que las cinco variables R2_* estén configuradas en back-end/.env. El probador, el estudio y la eliminación de fondo también necesitan el bucket y siguen desactivados sin él. La tienda de demostración no necesita bucket: sus imágenes se sirven desde copias que ambos frontends incluyen en public/mock-media/.

• Almacenamiento multimedia

Las imágenes subidas cargan despacio o a tamaño completo

Los frontends solo redimensionan y comprimen imágenes de los hosts en los que se construyeron para confiar. Una imagen de tu bucket en cualquier otro host se sigue mostrando, pero sin optimizar.

1. 01

   Indica el host público de tu bucket

   Sin Docker, pon en NEXT_PUBLIC_MEDIA_HOSTNAME del .env de cada frontend el host de R2_PUBLIC_URL, por ejemplo pub-1234.r2.dev. Con Docker Compose, pon MEDIA_HOSTNAME=pub-1234.r2.dev en un archivo .env junto a docker-compose.yml. Escribe solo el host, sin https:// ni barra final.
2. 02

   Vuelve a compilar los frontends

   El host se compila dentro. Reinicia yarn dev y reconstruye para producción, o vuelve a ejecutar docker compose up --build.

Las solicitudes se bloquean en tus propios dominios

Access to fetch at 'https://api.your-domain.com/api/…' from origin 'https://shop.your-domain.com' has been blocked by CORS policy

La API solo responde a los navegadores desde las direcciones de CORS_ORIGIN, y las notificaciones en directo del panel solo desde FRONTEND_URL. Ambas usan por defecto los dos puertos locales, así que en tus propios dominios deben indicar tus sitios.

CORS_ORIGIN=https://shop.your-domain.com,https://admin.your-domain.com
FRONTEND_URL=https://admin.your-domain.com

Escribe cada dirección exactamente como la muestra el navegador, con https:// y sin barra final, y luego reinicia la API. Con Docker Compose, configura en su lugar SITE_URL, ADMIN_URL y API_URL en el .env junto a docker-compose.yml y ejecuta docker compose up --build: el archivo compose construye ambas listas a partir de ellas.

• Pasar a producción

El contenedor de la API no encuentra su entrypoint

exec /usr/local/bin/docker-entrypoint.sh: no such file or directory

El script tiene finales de línea de Windows, que un editor o Git en Windows pueden añadir. El back-end/Dockerfile incluido los elimina durante la construcción, así que esto solo aparece con una imagen construida a partir de un Dockerfile modificado. Conserva su línea sed -i 's/\r$//', o guarda el script con finales de línea LF, y luego reconstruye sin la caché.

docker compose build --no-cache api
docker compose up

La carpeta se ve diferente

Ejecuta los comandos dentro de la carpeta en la que se extrae el ZIP. Si no tienes el comando unzip, extráelo con tu gestor de archivos; algunas herramientas añaden una carpeta extra con el nombre del ZIP, así que entra en la carpeta interior.

Empieza de cero con datos de demostración nuevos

Con Docker Compose, desde la carpeta e-commerce-1:

docker compose down -v
docker compose up

Con un contenedor de API independiente, elimina primero el contenedor (docker ps -a lo muestra, docker rm -f con su id lo elimina), luego borra el volumen y vuelve a ejecutarlo:

docker volume rm ecommerce-data
docker run -p 8000:8000 -v ecommerce-data:/data -e SEED_DEMO_DATA=true ecommerce-api

Sin Docker, detén la API y luego:

rm -f database.sqlite* && yarn seed

En PowerShell:

Remove-Item database.sqlite*; yarn seed

Volver a ejecutar yarn seed sobre una base de datos que conservas no es un reinicio: solo añade lo que falta y nunca restablece un valor que cambiaste en el panel. En MySQL, yarn db:reset elimina todas las tablas antes de yarn seed.

Empieza de cero con la tienda de ejemplo

Sin API, tus cambios se guardan en el navegador. Para recuperar la tienda de ejemplo, ejecuta esto en la consola del navegador, en la página de la aplicación:

localStorage.removeItem("mock_db_v1"); location.reload();