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 Full Stack, ou vos docker build et docker run pour le pack Admin Dashboard.

Un port est déjà utilisé

ports are not available: exposing port TCP 0.0.0.0:3030 … bind: address already in use
Bind for 0.0.0.0:3030 failed: port is already allocated
Error: listen EADDRINUSE: address already in use :::3030

Les deux premières lignes viennent de Docker, la dernière de yarn dev ou yarn start. Un autre programme écoute déjà sur 3030 ou 8000 : souvent un lancement précédent du tableau de bord, 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 :3030

   Sous Windows, dans PowerShell :

   TerminalCopier

   netstat -ano | findstr :3030
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 lancé avec docker run. Puis redémarrez le tableau de bord.
3. 03

   Ou lancer le tableau de bord sur d'autres ports

   Avec le Full Stack dans Docker, créez un fichier nommé .env dans le dossier dashboard-2-full-stack, à côté de docker-compose.yml, avec le port voulu. DASHBOARD_PORT déplace le tableau de bord et API_PORT l'API ; les adresses que les applications utilisent, CORS_ORIGIN compris, suivent d'elles-mêmes.

   dashboard-2-full-stack/.envCopier

   DASHBOARD_PORT=3040

   Relancez ensuite la même commande. Un démarrage qui a échoué reprend là où il s'était arrêté :

   Terminaldans dashboard-2-full-stackCopier

   docker compose up --build

   Résultat attendu: Le tableau de bord répond sur son nouveau port, ici localhost:3040Local.

• Pack Admin Dashboard dans Docker : changez le numéro à gauche de -p, par exemple docker run -p 3040:3030 dashboard-2, et ouvrez localhost:3040Local. L'application dans le conteneur écoute toujours sur 3030.
• Sans Docker : définissez PORT=3040 dans le .env du tableau de bord (créez le fichier avec cette seule ligne si vous n'en avez pas), ou lancez PORT=3040 yarn dev sous macOS et Linux. Avec une API, ajoutez aussi la nouvelle adresse à CORS_ORIGIN et FRONTEND_URL de l'API.
• L'API sans Docker : changez PORT dans back-end/.env, ainsi que NEXT_PUBLIC_API_BASE_URL et NEXT_PUBLIC_WEBSOCKET_BASE_URL dans le .env du tableau de bord, ensemble.

Le build Docker échoue

Le premier build télécharge les images de base, chaque dépendance et la police arabe du tableau de bord depuis Google Fonts, puis construit les images. Il s'arrête avec « failed to solve » et l'étape en échec quand quelque chose bloque.

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

docker compose build --no-cache
docker compose up

Pour le pack Admin Dashboard, ajoutez --no-cache à votre commande docker build.

Un premier démarrage qui semble bloqué est généralement encore en train de remplir les données d'exemple. Le tableau de bord ne démarre que lorsque l'API se déclare en bonne santé, ce qui peut prendre jusqu'à une minute.

Yarn indique la version 1.22

This project's package.json defines "packageManager": "yarn@4.8.1…". 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), installez-le d'abord avec npm install -g corepack.

Le tableau de bord ne démarre pas sur un Node.js plus ancien

node: bad option: --env-file-if-exists=.env

yarn dev et yarn start du tableau de bord lisent .env avec une option ajoutée à Node.js dans la version 22.9. Vérifiez la vôtre :

node -v

Si elle affiche une version inférieure à 22.9, installez Node.js 22.9 ou plus récent, relancez corepack enable, supprimez le dossier node_modules de l'application et relancez yarn install. Avec Docker, rien de 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 dashboard origin (comma separated if there are several), …

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 back-end 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`. Définissez-le sur l'adresse du tableau de bord.

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 de l'API

La connexion échoue

• Vérifiez le compte. Le Super Admin est admin@example.com avec Admin@123 ; les autres admins d'exemple utilisent admin123.
• « That email and password combination didn't work. Please try again. » répond à un mauvais mot de passe comme à un e-mail inconnu, et aussi à une base sans comptes. Sans Docker, lancez yarn seed dans back-end : yarn dev crée les tables tout seul, mais seul le seed ajoute les comptes.
• « Too many failed sign-in attempts. Wait 15 minutes, then try again. » Une adresse a échoué RATE_LIMIT_LOGIN connexions (10 par défaut) en 15 minutes. Attendez, ou redémarrez l'API : le compteur est gardé dans sa mémoire.
• La page de connexion ne répond jamais. Le tableau de bord ne peut pas joindre l'API : voyez le problème suivant.
• Vous avez changé le mot de passe du Super Admin et vous ne l'avez plus : repartez de zéro avec des données d'exemple neuves, plus bas.

La connexion échoue

• Sur la fausse API, connectez-vous avec admin@example.com et Admin@123, ou avec un Viewer d'exemple comme john.smith@admin.com avec admin123. Ces comptes vivent dans votre navigateur : un mot de passe que vous y avez changé reste changé jusqu'à ce que vous effaciez les données du site.
• Sur votre propre API, le compte doit y exister. Sur l'API de ce template, le seed ajoute les mêmes comptes. Si aucun compte ne fonctionne, le tableau de bord ne joint peut-être pas l'API : voyez le problème suivant.

Les pages restent vides et le navigateur signale une erreur CORS

Access to XMLHttpRequest at 'http://localhost:8000/api/auth/login' from origin 'http://localhost:3040' has been blocked by CORS policy

La console du navigateur affiche cette ligne quand le tableau de bord 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 http://localhost:3030 par défaut.

CORS_ORIGIN=http://localhost:3040
FRONTEND_URL=http://localhost:3040

• É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 s'il y en a plusieurs. Puis redémarrez l'API.
• FRONTEND_URL est la seule adresse que les mises à jour des permissions en direct acceptent. Déplacez-la avec le tableau de bord.
• Avec le Full Stack dans Docker, vous ne les modifiez pas : DASHBOARD_PORT et DASHBOARD_URL dans le .env à côté de docker-compose.yml les définissent.
• Un tableau de bord qui ne peut pas du tout joindre l'API, 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 NEXT_PUBLIC_API_BASE_URL du tableau de bord nomme cette API.

Le tableau de bord affiche des données d'exemple au lieu de mon API

Sample data
No API is connected (NEXT_PUBLIC_API_BASE_URL is empty), so the dashboard runs on built-in sample data. …

Le tableau de bord a été construit sans adresse d'API, il fonctionne donc sur sa fausse API intégrée. Cela arrive sans fichier .env, avec NEXT_PUBLIC_API_BASE_URL= vide, ou avec une image Docker construite sans le --build-arg.

• Sans Docker : cp .env.example .env dans le dossier du tableau de bord, vérifiez NEXT_PUBLIC_API_BASE_URL, puis redémarrez yarn dev, ou relancez yarn build pour un build de production.
• Docker, pack Admin Dashboard : reconstruisez l'image avec --build-arg NEXT_PUBLIC_API_BASE_URL=…, comme dans le guide d'installation.
• Docker Compose : le fichier compose construit toujours le tableau de bord avec l'adresse de l'API, donc cet avis n'y apparaît pas.

• La fausse API intégrée

Une modification du .env du tableau de bord 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.

Un changement de rôle n'atteint le tableau de bord qu'après un rechargement

Quand les permissions d'un rôle changent, l'API le signale par WebSocket au tableau de bord de chaque admin connecté, et les menus et boutons suivent sans rechargement. Le tableau de bord se connecte à NEXT_PUBLIC_WEBSOCKET_BASE_URL, l'adresse de l'API sans /api, et l'API n'accepte la connexion que depuis FRONTEND_URL, l'adresse du tableau de bord lui-même.

• Réglez les deux sur l'endroit où les applications tournent vraiment, puis redémarrez l'API et reconstruisez le tableau de bord.
• Un FRONTEND_URL non défini n'accepte que http://localhost:3030.
• Le tableau de bord relit aussi les permissions à chaque page qu'il ouvre, donc rien ne reste périmé longtemps.

L'assistant IA demande une clé d'API

The server has no key for this model's provider. Add your own API key to keep going.

L'API n'a pas de clé pour le fournisseur du modèle que vous avez choisi. Collez votre propre clé dans la boîte de dialogue, elle reste dans votre navigateur, ou ajoutez la clé du fournisseur à back-end/.env et redémarrez l'API (avec Docker Compose, relancez docker compose up).

gemini-3.6-flash 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.

Le fournisseur a refusé la requête parce que le quota de la clé est épuisé, ce qui est courant avec une clé gratuite. Choisissez un autre modèle dans le sélecteur, ou réessayez plus tard.

• L'assistant IA

Une photo ne peut pas être envoyée

Image uploads are not set up on this server yet. Add the Cloudflare R2 settings to the API environment to turn them on.

Les photos de profil et les images jointes de l'assistant sont stockées dans un bucket Cloudflare R2. Définissez les cinq variables R2_* dans back-end/.env et redémarrez l'API. Tout le reste fonctionne sans elles.

• Envois d'images

Le message d'accueil n'affiche pas la météo

La météo du message d'accueil de la vue d'ensemble demande une clé WeatherAPI.com dans WEATHER_API_KEY, lue par le serveur propre au tableau de bord. Sans elle, le message s'affiche sans la météo et rien d'autre ne change.

• Sans Docker, dans le .env du tableau de bord, puis redémarrez.
• Avec Docker Compose, dans le .env à côté de docker-compose.yml, puis relancez docker compose up.
• Avec l'image du tableau de bord, sur docker run : -e WEATHER_API_KEY=....

MySQL refuse de démarrer ou de remplir la base

L'API crée ses tables dans une base qui existe déjà ; elle ne crée pas la base elle-même. Créez d'abord une base vide, donnez son nom à DB_DATABASE dans back-end/.env, puis lancez yarn seed.

• Vérifiez les cinq valeurs de connexion DB_* et que DB_TYPE=mysql.
• Avec NODE_ENV=production, l'API en cours d'exécution ne crée jamais de tables : yarn seed:prod doit donc être lancé une fois après yarn build, avant le premier démarrage.
• L'image Docker ne crée la base elle-même que sur SQLite. Sur MySQL, lancez vous-même node dist/database/seeder.js une fois dans le conteneur.

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

Le dossier ne correspond pas

Exécutez les commandes dans le dossier où le ZIP est extrait. Si la commande unzip est absente, extrayez-le plutôt avec votre gestionnaire de fichiers ; certains outils ajoutent un dossier supplémentaire portant le nom du ZIP : placez-vous alors dans le dossier intérieur.

Repartir de zéro avec des données d'exemple neuves

Avec le Full Stack dans Docker, depuis le dossier dashboard-2-full-stack :

docker compose down -v
docker compose up

Sans Docker, arrêtez l'API, puis dans back-end :

rm -f database.sqlite* && yarn seed

Dans PowerShell :

Remove-Item database.sqlite*; yarn seed

Réinitialiser les données d'exemple de la fausse API

Sur la fausse API intégrée, les données d'exemple et tout ce que vous avez modifié vivent dans votre navigateur. Effacez les données du site pour l'adresse du tableau de bord dans les paramètres de votre navigateur et rechargez : les exemples reviennent tels qu'ils étaient livrés.