Dépannage

Docker n'est pas lancé

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

Les anciennes versions de Docker affichent plutôt « Cannot connect to the Docker daemon ». Dans les deux cas, le moteur Docker n'est pas démarré.

1. 01

   Ouvrez Docker Desktop

   Lancez Docker Desktop et attendez qu'il indique que le moteur est en marche. Sous Linux, démarrez le service : sudo systemctl start docker.
2. 02

   Vérifiez que Docker répond

   TerminalCopier

   docker info

   Résultat attendu: Une section Server s'affiche au lieu d'une erreur.
3. 03

   Relancez votre commande de démarrage

   docker compose up --build pour le pack Full Stack, ou vos commandes docker build et docker run pour une application seule.

Un port est déjà utilisé

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

Les deux premières lignes viennent de Docker, la dernière de yarn dev. Un autre programme écoute déjà sur 3030, 3031 ou 8000 : souvent un lancement précédent de l'agence, ou le serveur de développement d'un autre projet.

1. 01

   Trouvez ce qui occupe le port

   Sous macOS ou Linux, avec le port indiqué dans le message :

   TerminalCopier

   lsof -i :3031

   Sous Windows, dans PowerShell :

   TerminalCopier

   netstat -ano | findstr :3031
2. 02

   Arrêtez-le

   Fermez ce programme, ou arrêtez le lancement précédent : Ctrl+C dans son terminal, docker compose down dans son dossier, ou docker stop pour un conteneur démarré avec docker run. Puis redémarrez l'agence.
3. 03

   Ou lancez l'agence sur d'autres ports

   Avec la pile complète dans Docker, créez un fichier nommé .env dans le dossier velra-real-estate-full-stack, à côté de docker-compose.yml, avec le port voulu. SITE_PORT déplace le site, ADMIN_PORT le tableau de bord et API_PORT l'API ; les adresses utilisées par les applications, CORS_ORIGIN compris, suivent d'elles-mêmes.

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

   ADMIN_PORT=3041

   Puis relancez la même commande. Un démarrage échoué reprend là où il s'est arrêté. Docker nomme un seul port occupé à la fois : s'il s'arrête sur un autre, ajoutez-le aussi au .env.

   Terminaldans velra-real-estate-full-stackCopier

   docker compose up --build

   Résultat attendu: L'application répond sur son nouveau port, ici localhost:3041Local.

Le build Docker échoue

Le premier build télécharge les images de base et toutes les dépendances, puis construit les images. Quand quelque chose bloque, il s'arrête avec « failed to solve » et l'étape qui a échoué.

• Pas de connexion ou délai dépassé : le build a besoin d'un accès à internet. Relancez la commande une fois en ligne ; les étapes terminées sont en cache.
• No space left on device : libérez de l'espace dans Docker Desktop, ou vérifiez ce que Docker occupe avec docker system df.
• L'échec survient toujours à la même étape : reconstruisez sans le cache, puis démarrez.
• Compose rejette `docker-compose.yml` lui-même, en citant `env_file` : votre Compose est antérieur à 2.24. Mettez à jour Docker Desktop, ou le plugin Compose sous Linux.

docker compose build --no-cache
docker compose up

Pour un pack à application unique, ajoutez --no-cache à votre commande docker build.

Un premier démarrage qui semble bloqué est généralement en train d'alimenter l'agence de démonstration. Le site et le tableau de bord ne démarrent que lorsque l'API se déclare en bonne santé.

Yarn indique la version 1.22

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

Chaque application fixe Yarn 4 via Corepack. Ce message signifie que Corepack n'est pas encore activé, et que c'est donc l'ancien Yarn global qui a répondu.

corepack enable

Puis relancez yarn install. Si votre Node.js n'a pas Corepack (Node.js 25 et plus récent ne l'inclut plus), installez-le d'abord avec npm install -g corepack. npm et pnpm ne sont pas utilisés : chaque application livre son propre yarn.lock.

Une installation ou un démarrage échoue avec une version ancienne de Node.js

Chaque application déclare Node.js 22 ou plus récent, et les images Docker tournent sous Node.js 24. Un Node.js plus ancien se manifeste par une installation qui échoue à construire un package, ou une application qui s'arrête au démarrage.

node -v

S'il affiche une version inférieure à 22, installez Node.js 22 ou plus récent, relancez corepack enable (sous Node.js 25 et plus récent, npm install -g corepack d'abord), puis supprimez le dossier node_modules de l'application et relancez yarn install. Avec Docker, rien de tout cela ne s'applique : les images apportent leur propre Node.js.

L'API s'arrête avant de démarrer

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, …

L'API vérifie ses paramètres avant de démarrer et affiche une ligne par problème. Les causes :

• Il n'y a pas de fichier `.env`, ou `JWT_SECRET` est vide. Créez le fichier dans le dossier de l'API avec cp .env.example .env.
• `JWT_SECRET` a encore la valeur d'exemple avec `NODE_ENV=production`. N'importe qui pourrait signer un jeton avec l'exemple public : un démarrage en production le refuse donc. Générez votre propre secret.
• `CORS_ORIGIN` est vide avec `NODE_ENV=production`. Indiquez l'adresse du site et celle du tableau de bord, séparées par une virgule.

Générez un secret avec :

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

Avec Docker, vous n'en avez pas besoin : un conteneur sans JWT_SECRET propre, ou avec celui de l'exemple, génère un secret et le conserve dans le volume de données.

• Paramètres essentiels de l'API

Le site n'a aucune annonce et personne ne peut se connecter

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

La base a été créée avec les tables seulement. Cela arrive quand le conteneur de l'API démarre sur un nouveau volume sans SEED_DEMO_DATA=true, quand la pile complète tourne avec SEED_DEMO_DATA=false dans le .env à côté de docker-compose.yml, ou, sans Docker, quand yarn db:sync a été lancé à la place de yarn seed. Il n'y a alors ni annonce ni compte pour se connecter.

• Sans Docker : lancez yarn seed dans le dossier de l'API. Il ajoute l'agence de démonstration et ses comptes aux tables existantes.
• Pile complète dans Docker : retirez SEED_DEMO_DATA=false du .env, puis docker compose down -v et docker compose up. Le volume de données est recréé avec l'agence de démonstration.
• Conteneur de l'API : supprimez le conteneur et son volume, puis relancez-le avec -e SEED_DEMO_DATA=true, comme dans Repartir de données de démonstration neuves, plus bas.

Le conteneur ne recharge jamais les données de démonstration dans une base existante, quelle que soit la valeur de SEED_DEMO_DATA : la variable ne compte donc que sur un nouveau volume.

La connexion échoue

• Vérifiez le compte. Le tableau de bord sur le port 3031 accepte admin@velra.example avec Admin@123, ou agent@velra.example avec Agent@123. Le site n'a pas de comptes.
• « Invalid email or password » répond aussi bien à un mauvais mot de passe, un e-mail inconnu qu'à une base sans compte. Vérifiez les points ci-dessous, un par un.
• La base n'a aucun compte quand elle a été créée avec SEED_DEMO_DATA=false. Voir Le site n'a aucune annonce et personne ne peut se connecter, plus haut.
• « Too many sign-in attempts. Try again in a few minutes. » Dix connexions échouées depuis une même adresse en 15 minutes bloquent le formulaire pour cette adresse jusqu'à ce que le plus ancien échec ait 15 minutes. Attendez, ou redémarrez l'API : le compte est gardé dans sa mémoire.
• « Network error. Please check your connection and try again » signifie que le tableau de bord ne peut pas joindre l'API : voir le problème de CORS plus bas.
• Vous avez changé un mot de passe et vous ne l'avez plus : repartez de données de démonstration neuves, plus bas.

La connexion échoue

• Vérifiez le compte et la route. Les admins se connectent sur POST /api/auth/login ; le Super Admin du seed est admin@velra.example avec Admin@123. Une connexion échouée répond 401 avec le même message, que l'e-mail ou le mot de passe soit faux.
• Aucun compte ne fonctionne : la base a été créée sans l'agence de démonstration. Lancez yarn seed, ou démarrez le conteneur avec -e SEED_DEMO_DATA=true sur un nouveau volume.
• Une réponse `429` signifie qu'une adresse a échoué 10 connexions en 15 minutes. Elle disparaît quand le plus ancien échec a 15 minutes, ou au redémarrage de l'API. RATE_LIMIT_LOGIN change ce nombre.

La connexion échoue

Le tableau de bord se connecte à l'API Velra, donc le compte doit y exister. Sur une API avec seed, connectez-vous avec admin@velra.example et Admin@123. Si aucun compte ne fonctionne, soit l'API a été démarrée sans ses données de démonstration (lancez yarn seed dans son dossier, ou démarrez son conteneur sur un nouveau volume avec -e SEED_DEMO_DATA=true), soit l'application ne peut pas joindre l'API : voir le problème suivant. Le site n'a pas de comptes.

Les pages indiquent « 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

Le site affiche la première ligne, et le tableau de bord affiche « Network error », quand le navigateur ne peut pas utiliser l'API. La console du navigateur affiche la seconde ligne quand un frontend tourne sur une adresse que l'API n'accepte pas. L'API ne répond aux navigateurs que depuis les adresses de CORS_ORIGIN, qui vaut par défaut http://localhost:3030 et http://localhost:3031. Un site ou un tableau de bord déplacé sur un autre port, ou servi sur votre propre domaine, est refusé tant qu'il n'est pas dans la liste.

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

• Écrivez chaque adresse exactement comme le navigateur l'affiche, avec le schéma et le port et sans barre oblique finale, séparées par des virgules. Puis redémarrez l'API.
• FRONTEND_URL est l'adresse du tableau de bord, depuis laquelle se connectent ses notifications en direct. Déplacez-la avec le tableau de bord.
• Pour un conteneur de l'API, passez les mêmes valeurs avec -e, par exemple -e CORS_ORIGIN=http://localhost:3030,http://localhost:3041.
• Avec le pack complet sous Docker, vous ne les modifiez pas : SITE_PORT, ADMIN_PORT, SITE_URL et ADMIN_URL dans le .env à côté de docker-compose.yml les définissent.
• Un frontend qui ne peut pas joindre l'API du tout, parce qu'elle est arrêtée ou à une autre adresse, échoue de la même façon, sans la ligne CORS. Vérifiez que localhost:8000/api/healthLocal répond, et que le NEXT_PUBLIC_API_BASE_URL du frontend désigne bien cette API.

• Déployer

L'onglet d'une page de bien indique « Property details » dans Docker

Le serveur propre au site lit le titre du bien pour l'onglet du navigateur, le premier rendu de la page et le sitemap. Dans un conteneur, localhost est le conteneur lui-même : ce serveur ne peut donc pas joindre une API sur votre ordinateur à http://localhost:8000. La page se charge quand même dans le navigateur, qui joint l'API directement.

Démarrez le conteneur du site avec l'adresse de l'API telle que le serveur la voit :

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 pile complète dans Docker la définit pour vous (http://api:8000/api). Sans Docker, ce n'est pas nécessaire.

Les photos des biens ne se chargent pas

Les photos du seed sont servies par l'API sur /media/velra/…, et chaque adresse de photo est construite à partir de PUBLIC_MEDIA_URL, qui vaut par défaut http://localhost:8000/media. Une photo s'affiche mal quand cette adresse ne joint pas l'API depuis le navigateur.

• L'API tourne sur un autre port ou un autre domaine. Définissez PUBLIC_MEDIA_URL avec l'adresse publique de l'API suivie de /media, par exemple -e PUBLIC_MEDIA_URL=http://localhost:8010/media avec docker run -p 8010:8000. Avec le pack complet sous Docker, API_PORT et API_URL la définissent pour vous.
• L'API a changé d'adresse après le premier démarrage. Redémarrez-la avec le nouveau PUBLIC_MEDIA_URL : au démarrage, elle fait pointer chaque photo stockée vers cette adresse, et son journal indique « Pointed … stored media URLs at … ».
• Les fichiers envoyés vers un bucket ne s'affichent pas. R2_PUBLIC_URL doit être l'adresse publique du bucket, et le bucket doit autoriser la lecture publique.
• Les photos se chargent, mais en taille réelle. Les frontends ne redimensionnent que les photos des hôtes https de NEXT_PUBLIC_MEDIA_HOSTNAME (avec Docker Compose, MEDIA_HOSTNAME), chacun écrit sans le chemin et séparés par des virgules, comme api.your-agency.com,pub-1234.r2.dev. Toute autre photo, comme celle d'une API sur localhost, se charge telle quelle. Reconstruisez le frontend après l'avoir modifié.

• Variables d'environnement

Une modification du .env d'un frontend n'a aucun effet

Chaque valeur NEXT_PUBLIC_* est compilée dans le JavaScript chargé par le navigateur au moment du build de l'application. Modifier le fichier ne change rien tant que l'application n'est pas reconstruite.

Le studio de mise en scène ou l'assistant demande une clé

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

L'assistant répond avec Google Gemini, OpenAI ou DeepSeek et s'active avec la clé de l'un d'eux dans le .env de l'API : GOOGLE_API_KEY, OPENAI_API_KEY ou DEEPSEEK_API_KEY, les trois que liste son message. Le studio de mise en scène génère avec Google uniquement, il a donc besoin de GOOGLE_API_KEY quoi qu'il y ait d'autre. Dans .env.example, les trois lignes sont en commentaire : un fichier copié démarre proprement et les deux fonctionnalités restent désactivées, sans rien facturer.

• Retirez le # devant la ligne de chaque clé que vous avez, collez votre vraie clé à la place de l'exemple, et redémarrez l'API.
• Avec Docker Compose, l'API lit aussi back-end/.env, donc un nouveau docker compose up suffit ; un conteneur d'API seul demande --env-file .env -e NODE_ENV=production sur son docker run.
• Rechargez la page du tableau de bord après le redémarrage.
• Un modèle absent du sélecteur de l'assistant appartient à un fournisseur dont la clé n'est pas définie : le sélecteur ne liste que les modèles des fournisseurs qui ont une clé.

L'assistant ne peut pas répondre avec le modèle choisi

{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.

L'assistant affiche l'un de ces messages à la place d'une réponse quand le fournisseur du modèle choisi refuse la requête, avec Google, OpenAI ou DeepSeek comme fournisseur, le nom du modèle et la variable de la clé renseignés. Il n'exécute que le modèle que vous avez choisi : il ne passe jamais seul à un autre et ne réessaie jamais de lui-même. Corrigez donc la cause ou choisissez un autre modèle dans la liste au-dessus du chat, puis appuyez sur « Try again ».

Une demande de visite ou le formulaire de contact est refusé

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.

• Trop tôt. Une visite doit commencer au moins une heure après l'instant présent, dans le fuseau horaire de l'agence (Asia/Dubai), quelle que soit l'horloge du visiteur.
• Trop de requêtes. Chaque adresse peut envoyer cinq formulaires de contact et cinq demandes de visite en dix minutes. Pendant vos tests, attendez, ou redémarrez l'API : les compteurs vivent dans sa mémoire.
• Derrière un reverse proxy, chaque visiteur peut ressembler au proxy et partager un seul quota : voir le problème suivant.

Chaque visiteur reçoit « Too many » derrière un proxy

La connexion, le formulaire de contact et les demandes de visite sont limités par adresse de visiteur. Derrière un reverse proxy, chaque visiteur peut ressembler à l'unique adresse du proxy et partager un seul quota. Indiquez à l'API combien de proxys se trouvent devant elle :

TRUST_PROXY=1

RATE_LIMIT_LOGIN change le nombre de connexions échouées autorisées. Les compteurs vivent dans la mémoire de l'API : un redémarrage les efface.

MySQL refuse de démarrer ou de remplir la base

L'API crée ses tables dans une base de données qui existe déjà ; elle ne crée pas la base elle-même. Créez d'abord une base vide, indiquez son nom dans DB_DATABASE du .env de l'API, puis lancez yarn seed (ou yarn db:sync pour les tables sans données de démonstration).

• Vérifiez les cinq valeurs de connexion DB_* et que DB_TYPE=mysql.
• Avec NODE_ENV=production, l'API en fonctionnement ne crée jamais de tables : l'une de ces commandes doit donc être lancée avant le premier démarrage (yarn seed:prod ou yarn db:sync:prod après yarn build).
• L'image Docker ne crée la base de données d'elle-même que sur SQLite. Sur MySQL, lancez vous-même une fois la commande des données de démonstration ou celle du schéma.

• Utiliser MySQL au lieu de SQLite

Le conteneur de l'API ne trouve pas son point d'entrée

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

Le script a des fins de ligne Windows, qu'un éditeur ou Git sous Windows peut ajouter. Le Dockerfile de l'API fourni les retire pendant le build, donc cela n'apparaît qu'avec une image construite à partir d'un Dockerfile modifié. Gardez sa ligne sed -i 's/\r$//', ou enregistrez le script avec des fins de ligne LF, puis reconstruisez sans le cache.

La commande unzip échoue ou le dossier est différent

caution: filename not matched:  velra-…zip

Ce message signifie que deux ZIP du même pack se trouvent dans le dossier, comme un ancien téléchargement à côté du nouveau, et que le * de la commande a correspondu aux deux. Supprimez l'ancien ZIP et relancez la commande, ou tapez le nom complet du fichier à la place du *.

Lancez les commandes suivantes dans le dossier où le ZIP s'extrait. Si la commande unzip est absente, extrayez-le avec votre gestionnaire de fichiers ; certains outils ajoutent un dossier supplémentaire nommé d'après le ZIP, placez-vous alors dans le dossier intérieur.

Repartir de données de démonstration neuves

Avec la pile complète dans Docker, depuis le dossier velra-real-estate-full-stack :

docker compose down -v
docker compose up

Avec un conteneur d'API seul, supprimez d'abord le conteneur (docker ps -a le liste, docker rm -f avec son identifiant le supprime), puis supprimez le volume velra-api-data et relancez-le. La pile complète garde ses données dans un autre volume, velra-data, que cela ne touche donc jamais.

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

Sans Docker, arrêtez l'API, puis dans son dossier :

rm -f database.sqlite* && yarn seed

Dans PowerShell :

Remove-Item database.sqlite*; yarn seed

Relancer yarn seed sur une base que vous conservez n'est pas une réinitialisation : il n'ajoute que ce qui manque et ne réinitialise jamais un mot de passe. yarn db:reset supprime chaque table, sur SQLite comme sur MySQL ; lancez yarn seed ensuite.