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 y la segunda de yarn dev. Otro programa ya escucha en 3030, 3031 o 8000: a menudo una ejecución anterior de Learnio 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 Learnio.
3. 03

   O ejecuta Learnio en otros puertos

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

   learnio-lms/.envCopiar

   ADMIN_PORT=3041

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

   Terminalen learnio-lmsCopiar

   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 los datos de demostración. El sitio 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.

corepack enable

En Node 26, que ya no incluye Corepack, instálalo primero con npm install -g corepack. Es normal que yarn install termine con "Done with warnings"; un fallo real termina con "Failed with errors".

La API se detiene antes de iniciarse

✖ The API cannot start. Fix these in back-end/.env:

La API revisa primero su configuración y enumera lo que hay que corregir. Las causas habituales:

• No hay archivo `.env`. Créalo en back-end/ con cp .env.example .env.
• `JWT_SECRET` está vacío, o tiene el valor de ejemplo con `NODE_ENV=production`. Genera tu propio secreto.
• `CORS_ORIGIN` está vacío con `NODE_ENV=production`. Indica el sitio para estudiantes y el panel de administración, separados por comas.
• `DB_TYPE` no es `sqlite` ni `mysql`.

• Lo esencial de la API

El inicio de sesión falla

• Comprueba la cuenta y la aplicación. Las cuentas del personal inician sesión en el panel de administración, en el puerto 3031: admin@learnio.com con Admin@123. El estudiante de demostración inicia sesión en el sitio para estudiantes, en el puerto 3030: demo@learnio.com con Demo@123.
• Revisa el registro de la API. "The database has no accounts, so nobody can sign in" significa que nunca se añadieron los datos 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 superadministrador 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" es la misma respuesta para un email sin cuenta y para una contraseña incorrecta, así que revisa ambos.
• "Too many attempts" significa que una misma dirección hizo más de 10 intentos en un formulario de inicio de sesión o de contraseña en un minuto, algo que un servidor en producción rechaza con 429. 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ñadieron los datos 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. El superadministrador es admin@learnio.com con Admin@123, y el estudiante de demostración demo@learnio.com con Demo@123. Un inicio de sesión fallido responde 401 con el mismo mensaje, tanto si falla el email como la contraseña.
• Una respuesta `429` significa que una misma dirección hizo más de 10 intentos en una ruta de inicio de sesión, registro o contraseña en un minuto. La cabecera Retry-After indica cuántos segundos esperar.

El inicio de sesión falla

Con la simulación en el navegador, cualquier correo y contraseña te permiten iniciar sesión como superadministrador. Cuando conectes una API, inicia sesión con una cuenta que exista en ella; el superadministrador de demostración es admin@learnio.com con Admin@123.

Aparece un aviso "Sample data"

El frontend no pudo conectar con la API, así que muestra en su lugar sus datos de ejemplo incluidos.

1. 01

   Comprueba que la API responde

   Abre localhost:8000/api/healthLocal. Debe responder con el estado ok.
2. 02

   Comprueba la dirección de la API en el frontend

   NEXT_PUBLIC_API_BASE_URL en el .env del frontend debe ser la dirección de la API incluyendo /api, por ejemplo http://localhost:8000/api.
3. 03

   Reinicia el frontend

   La dirección queda compilada en la aplicación. Reinicia yarn dev después de cambiarla; con Docker, vuelve a ejecutar docker compose up --build.

Las imágenes de los cursos no se ven tras conectar R2

Con claves R2_* en back-end/.env, la API sirve los archivos desde tu bucket, y los frontends solo muestran imágenes de los hosts en los que se compilaron para confiar. Sin ese host, cada miniatura de curso muestra su texto alternativo en lugar de la imagen.

1. 01

   Indica el host público de tu bucket

   Con Docker, pon MEDIA_HOSTNAME=your-bucket.r2.dev en un archivo .env junto a docker-compose.yml. Sin Docker, define NEXT_PUBLIC_MEDIA_HOSTNAME en el .env de cada frontend. Escribe solo el host, sin https://.
2. 02

   Vuelve a compilar los frontends

   El host queda compilado. Ejecuta de nuevo docker compose up --build, o reinicia yarn dev y vuelve a compilar para producción.

   Resultado esperado: Las miniaturas de los cursos se cargan desde tu bucket.

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, desde la carpeta learnio-lms:

docker compose down -v
docker compose up

Sin Docker, detén la API y luego:

rm -f database.sqlite && yarn seed

En PowerShell:

Remove-Item database.sqlite; yarn seed

Ejecutar yarn seed de nuevo sobre una base de datos que conservas no la restablece: los roles mantienen los permisos que les diste y los ajustes, los valores que guardaste. Solo una base de datos nueva recupera los de serie.