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:3031 … bind: address already in use
Bind for 0.0.0.0:3031 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3031

Las dos primeras líneas vienen de Docker y la última de yarn dev. Otro programa ya escucha en el 3030, el 3031 o el 8000: a menudo una ejecución anterior de la agencia, o el servidor de desarrollo de otro proyecto.

1. 01

   Averigua qué ocupa el puerto

   En macOS o Linux, con el puerto del mensaje:

   TerminalCopiar

   lsof -i :3031

   En Windows, en PowerShell:

   TerminalCopiar

   netstat -ano | findstr :3031
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. Luego inicia la agencia otra vez.
3. 03

   O ejecuta la agencia en otros puertos

   Con la pila completa en Docker, crea un archivo llamado .env en la carpeta velra-real-estate-full-stack, junto a docker-compose.yml, con el puerto que necesites. SITE_PORT mueve el sitio web, ADMIN_PORT el panel y API_PORT la API; las direcciones que usan las aplicaciones, CORS_ORIGIN incluido, las siguen por sí solas.

   velra-real-estate-full-stack/.envCopiar

   ADMIN_PORT=3041

   Luego ejecuta el mismo comando otra vez. Un inicio fallido continúa donde se detuvo. Docker nombra un solo puerto ocupado cada vez: si se detiene en otro, añade ese también al .env.

   Terminalen velra-real-estate-full-stackCopiar

   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.
• Compose rechaza el propio `docker-compose.yml`, nombrando `env_file`: tu Compose es anterior a la 2.24. Actualiza Docker Desktop, o el plugin de Compose en Linux.

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 atascado suele seguir cargando la agencia de demostración. El sitio web y el panel solo inician cuando la API indica 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

Luego ejecuta yarn install otra vez. Si tu Node.js no tiene Corepack (Node.js 25 y posteriores lo omiten), instálalo antes con npm install -g corepack. No se usan npm ni pnpm: cada aplicación incluye su propio yarn.lock.

Una instalación o un inicio falla con una versión antigua de Node.js

Cada aplicación declara Node.js 22 o más reciente, y las imágenes de Docker funcionan con Node.js 24. Un Node.js más antiguo se nota en una instalación que no logra construir un paquete, o en una aplicación que se detiene al iniciar.

node -v

Si muestra una versión inferior a la 22, instala Node.js 22 o más reciente, ejecuta corepack enable otra vez (en Node.js 25 y posteriores, antes npm install -g corepack), luego elimina la carpeta node_modules de la aplicación y ejecuta yarn install otra vez. Con Docker nada de esto se aplica: las imágenes traen su propio Node.js.

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, so anyone can sign a token for any account. …
The API cannot start: CORS_ORIGIN is not set. List the website and agency dashboard origins, comma separated, …

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 la carpeta de la API 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`. Escribe las direcciones del sitio web 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

El sitio web no tiene anuncios y nadie puede iniciar sesión

→ No database at /data/database.sqlite. Creating the tables, no data (set SEED_DEMO_DATA=true for the demo).

La base de datos se creó solo con tablas. Eso ocurre cuando el contenedor de la API inicia en un volumen nuevo sin SEED_DEMO_DATA=true, cuando la pila completa se ejecuta con SEED_DEMO_DATA=false en el .env junto a docker-compose.yml, o, sin Docker, cuando se ejecutó yarn db:sync en lugar de yarn seed. No hay anuncios ni cuenta con la que iniciar sesión.

• Sin Docker: ejecuta yarn seed en la carpeta de la API. Añade la agencia de demostración y sus cuentas a las tablas que tienes.
• Pila completa en Docker: quita SEED_DEMO_DATA=false del .env, luego docker compose down -v y docker compose up. El volumen de datos se crea de nuevo con la agencia de demostración.
• Contenedor de la API: elimina el contenedor, borra su volumen y vuelve a ejecutarlo con -e SEED_DEMO_DATA=true, como en Empieza de cero con datos de demostración nuevos, más abajo.

El contenedor nunca vuelve a cargar datos en una base de datos existente, diga lo que diga SEED_DEMO_DATA, así que la variable solo importa en un volumen nuevo.

El inicio de sesión falla

• Comprueba la cuenta. El panel en el puerto 3031 acepta admin@velra.example con Admin@123, o agent@velra.example con Agent@123. El sitio web no tiene cuentas.
• "Invalid email or password" responde igual a una contraseña incorrecta, a un correo desconocido y a una base de datos sin cuentas. Revisa los puntos siguientes por orden.
• La base de datos no tiene cuentas cuando se creó con SEED_DEMO_DATA=false. Consulta El sitio web no tiene anuncios y nadie puede iniciar sesión, más arriba.
• "Too many sign-in attempts. Try again in a few minutes." Diez inicios de sesión fallidos desde una misma dirección en 15 minutos bloquean el formulario para esa dirección hasta que el fallo más antiguo cumpla 15 minutos. Espera, o reinicia la API: la cuenta se guarda en su memoria.
• "Network error. Please check your connection and try again" significa que el panel no puede conectar con la API: consulta el problema de CORS más abajo.
• Cambiaste una contraseña y ya no la tienes: empieza de nuevo con datos de demostración nuevos, más abajo.

El inicio de sesión falla

• Comprueba la cuenta y la ruta. Los administradores inician sesión en POST /api/auth/login; el Super Admin de la carga inicial es admin@velra.example con Admin@123. Un inicio de sesión fallido responde 401 con el mismo mensaje tanto si el correo como si la contraseña son incorrectos.
• Ninguna cuenta funciona: la base de datos se creó sin la agencia de demostración. Ejecuta yarn seed, o inicia el contenedor con -e SEED_DEMO_DATA=true en un volumen nuevo.
• Una respuesta `429` significa que una dirección falló 10 inicios de sesión en 15 minutos. Se levanta cuando el fallo más antiguo cumple 15 minutos, o cuando la API se reinicia. RATE_LIMIT_LOGIN cambia el número.

El inicio de sesión falla

El panel inicia sesión contra la API de Velra, así que la cuenta tiene que existir allí. En una API con los datos cargados, inicia sesión con admin@velra.example y Admin@123. Si ninguna cuenta funciona, o bien la API se inició sin sus datos de demostración (ejecuta yarn seed en su carpeta, o inicia su contenedor en un volumen nuevo con -e SEED_DEMO_DATA=true), o bien la aplicación no puede conectar con la API: consulta el siguiente problema. El sitio web no tiene cuentas.

Las páginas dicen "We could not load this right now"

We could not load this right now
Access to XMLHttpRequest at 'http://localhost:8000/api/…' from origin 'http://localhost:3041' has been blocked by CORS policy

El sitio web muestra la primera línea, y el panel dice "Network error", cuando el navegador no puede usar la API. La consola del navegador muestra la segunda línea cuando un frontend funciona en una dirección que la API no acepta. La API responde a los navegadores solo desde las direcciones de CORS_ORIGIN, que por defecto es http://localhost:3030 y http://localhost:3031. Un sitio web o un panel movido a otro puerto, o servido en tu propio dominio, es rechazado hasta que figure en la lista.

CORS_ORIGIN=http://localhost:3030,http://localhost:3041
FRONTEND_URL=http://localhost:3041

• Escribe cada dirección exactamente como la muestra el navegador, con el esquema y el puerto y sin barra final, separadas por comas. Luego reinicia la API.
• FRONTEND_URL es la dirección del panel, desde la que se conectan sus notificaciones en directo. Muévela junto con el panel.
• Para un contenedor de la API, pasa los mismos valores con -e, por ejemplo -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• Con el paquete completo en Docker no editas estos valores: los configuran SITE_PORT, ADMIN_PORT, SITE_URL y ADMIN_URL en el .env junto a docker-compose.yml.
• Un frontend que no llega a la API en absoluto, porque está detenida o en otra dirección, falla de la misma forma pero sin la línea de CORS. Comprueba que localhost:8000/api/healthLocal responde y que NEXT_PUBLIC_API_BASE_URL del frontend apunta a esa API.

• Despliégalo

La pestaña de una página de propiedad dice "Property details" en Docker

El propio servidor del sitio web lee el título de la propiedad para la pestaña del navegador, el primer renderizado de la página y el mapa del sitio. Dentro de un contenedor localhost es el propio contenedor, así que ese servidor no puede llegar a una API de tu equipo en http://localhost:8000. La página sigue cargando en el navegador, que llega a la API directamente.

Inicia el contenedor del sitio web con la dirección de la API tal como la ve el servidor:

docker run -p 3030:3030 -e API_INTERNAL_URL=http://host.docker.internal:8000/api --add-host=host.docker.internal:host-gateway velra-website

La pila completa en Docker lo define por ti (http://api:8000/api). Sin Docker no hace falta.

Las fotos de las propiedades no cargan

Las fotos de la carga inicial las sirve la API en /media/velra/…, y cada dirección de foto se construye a partir de PUBLIC_MEDIA_URL, que por defecto es http://localhost:8000/media. Una foto se rompe cuando esa dirección no llega a la API desde el navegador.

• La API funciona en otro puerto o dominio. Configura PUBLIC_MEDIA_URL con la dirección pública de la API seguida de /media, por ejemplo -e PUBLIC_MEDIA_URL=http://localhost:8010/media con docker run -p 8010:8000. Con el paquete completo en Docker, API_PORT y API_URL lo configuran por ti.
• La API se movió después del primer inicio. Reiníciala con el nuevo PUBLIC_MEDIA_URL: al iniciar, apunta cada foto guardada a esa dirección, y su registro dice "Pointed … stored media URLs at …".
• Los archivos subidos a un bucket no cargan. R2_PUBLIC_URL debe ser la dirección pública del bucket, y el bucket debe permitir lecturas públicas.
• Las fotos cargan, pero a tamaño completo. Los frontends solo redimensionan las fotos de los hosts https de NEXT_PUBLIC_MEDIA_HOSTNAME (con Docker Compose, MEDIA_HOSTNAME), cada uno escrito solo como host y separados por comas, como api.your-agency.com,pub-1234.r2.dev. Cualquier otra foto, como una de una API en localhost, se carga tal cual. Vuelve a construir el frontend después de cambiarlo.

• Variables de entorno

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.

El estudio de amueblado o el asistente piden una clave

Generation needs a Google Gemini key
The assistant needs an AI provider key

El asistente responde con Google Gemini, OpenAI o DeepSeek y se activa con la clave de cualquiera de ellos en el .env de la API: GOOGLE_API_KEY, OPENAI_API_KEY o DEEPSEEK_API_KEY, las tres que enumera su aviso. El estudio de amueblado genera solo con Google, así que necesita GOOGLE_API_KEY sea lo que sea que se defina además. En .env.example las tres líneas están comentadas, así que un archivo copiado inicia limpio y ambas funciones siguen desactivadas, sin facturar nada.

• Quita el # delante de la línea de cada clave que tengas, pega tu clave real sobre el ejemplo y reinicia la API.
• Con Docker Compose la API también lee back-end/.env, así que basta con docker compose up otra vez; un contenedor de API suelto necesita --env-file .env -e NODE_ENV=production en su docker run.
• Recarga la página del panel después del reinicio.
• Un modelo que falta en el selector del asistente pertenece a un proveedor cuya clave no está definida: el selector solo enumera los modelos de los proveedores con clave.

El asistente no puede responder con el modelo elegido

{provider} did not accept the API key, so {model} could not answer. Check that {variable} holds a valid {provider} key, then try again or pick a model from another provider.
The {provider} account behind this API key has no credit left, so {model} could not answer. Add credit or billing on that account, or pick a model from another provider.
{model} has no requests left on this API key right now. Pick a different model from the list above the chat, or try again in a few minutes.
{provider} has no room for {model} right now. Try again in a minute, or pick another model from the list above the chat.

El asistente muestra uno de estos mensajes en lugar de una respuesta cuando el proveedor del modelo elegido rechaza la petición, con Google, OpenAI o DeepSeek como proveedor, el nombre del modelo y la variable de la clave rellenados. Solo ejecuta el modelo que elegiste: nunca cambia a otro por sí solo ni reintenta por su cuenta, así que corrige la causa o elige otro modelo en la lista sobre el chat y luego pulsa Try again.

Se rechaza una solicitud de visita o el formulario de contacto

Choose a date and time at least one hour from now, in Dubai time.
Too many requests were sent from this connection. Please wait a few minutes and try again.

• Demasiado pronto. Una visita tiene que empezar al menos una hora después de ahora, en la zona horaria de la agencia (Asia/Dubai), diga lo que diga el reloj del visitante.
• Demasiadas peticiones. Cada dirección puede enviar cinco formularios de contacto y cinco solicitudes de visita en diez minutos. Mientras pruebas, espera, o reinicia la API: las cuentas están en su memoria.
• Detrás de un proxy inverso, todos los visitantes pueden parecer el proxy y compartir una misma cuota: consulta el siguiente problema.

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

El inicio de sesión, el formulario de contacto y las solicitudes de visita se limitan por dirección de visitante. Detrás de un proxy inverso, todos los visitantes pueden parecer la única dirección del proxy y compartir una misma cuota. Indica a la API cuántos proxies hay delante de ella:

TRUST_PROXY=1

RATE_LIMIT_LOGIN cambia el número de inicios de sesión fallidos permitidos. Las cuentas están en la memoria de la API, así que un reinicio las borra.

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 en sí. Crea primero una base de datos vacía, pon su nombre en DB_DATABASE en el .env de la API y luego ejecuta yarn seed (o yarn db:sync para las tablas sin datos 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 (yarn seed:prod o yarn db:sync:prod después de yarn build).
• La imagen de Docker crea la base de datos por sí sola solo con SQLite. Con MySQL, ejecuta tú mismo una vez la carga de datos o el comando del esquema.

• Usa MySQL en lugar de SQLite

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 Dockerfile de la API 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 vuelve a construir sin la caché.

El comando unzip falla o la carpeta se ve distinta

caution: filename not matched:  velra-…zip

Ese mensaje significa que hay dos ZIP del mismo paquete en la carpeta, como una descarga anterior junto a la nueva, y el * del comando coincidió con ambos. Elimina el ZIP más antiguo y ejecuta el comando otra vez, o escribe el nombre completo del archivo en lugar del *.

Ejecuta los siguientes comandos dentro de la carpeta en la que se extrae el ZIP. Si falta 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 interior.

Empieza de cero con datos de demostración nuevos

Con la pila completa en Docker, desde la carpeta velra-real-estate-full-stack:

docker compose down -v
docker compose up

Con un solo contenedor de API, elimina primero el contenedor (docker ps -a lo lista, docker rm -f con su id lo elimina), luego elimina el volumen velra-api-data y ejecútalo otra vez. La pila completa guarda sus datos en un volumen distinto, velra-data, así que esto nunca lo toca.

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

Sin Docker, detén la API y luego, en su carpeta:

rm -f database.sqlite* && yarn seed

En PowerShell:

Remove-Item database.sqlite*; yarn seed

Ejecutar yarn seed otra vez en una base de datos que conservas no es un restablecimiento: solo añade lo que falta y nunca restablece una contraseña. yarn db:reset elimina todas las tablas, tanto en SQLite como en MySQL; ejecuta yarn seed después.