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:3030 … bind: address already in use
Error: listen EADDRINUSE: address already in use :::3030

La première ligne vient de Docker, la seconde de yarn dev. Un autre programme écoute déjà sur 3030, 3031 ou 8000 : souvent une exécution précédente de la boutique, ou le serveur de développement d'un autre projet.

1. 01

   Trouvez ce qui occupe le port

   Sous macOS ou Linux :

   TerminalCopier

   lsof -i :3030

   Sous Windows, dans PowerShell :

   TerminalCopier

   netstat -ano | findstr :3030
2. 02

   Arrêtez-le

   Fermez ce programme, ou arrêtez l'exécution précédente : Ctrl+C dans son terminal, docker compose down dans son dossier, ou docker stop pour un conteneur démarré avec docker run. Puis relancez la boutique.
3. 03

   Ou lancez la boutique sur d'autres ports

   Avec le Full Stack sous Docker, créez un fichier nommé .env dans le dossier e-commerce-1, à côté de docker-compose.yml, avec le port voulu. SITE_PORT déplace la boutique, ADMIN_PORT l'admin et API_PORT l'API ; les adresses utilisées par les applications suivent d'elles-mêmes.

   e-commerce-1/.envCopier

   ADMIN_PORT=3041

   Puis relancez la même commande. Après un démarrage raté, elle reprend là où elle s'était arrêtée :

   Terminaldans e-commerce-1Copier

   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.

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 encore en train de remplir la boutique de démonstration. La boutique et le tableau de bord admin ne démarrent qu'une fois que 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, installez-le d'abord avec npm install -g corepack.

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, …
✖ The API cannot start: CORS_ORIGIN is not set. List the storefront and admin dashboard origins, …

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`. Indiquez les adresses de la boutique et du tableau de bord admin, 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 health check répond 503

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

/api/health répond 503 tant que la base de données ne répond pas et ne contient pas ses tables. La seconde ligne est ce qu'affiche le journal de l'API au démarrage quand les tables manquent.

• Sans Docker, en développement : exécutez yarn seed dans back-end/ (tables et boutique de démonstration), ou yarn db:sync (tables uniquement), puis redémarrez l'API.
• Avec `NODE_ENV=production` : l'API ne crée pas de tables au démarrage. Exécutez yarn db:sync:prod (tables vides) ou yarn seed:prod (avec la boutique de démonstration) une fois, après yarn build.
• Avec Docker sur SQLite : le conteneur crée lui-même la base de données au premier démarrage. Sur MySQL, ce n'est pas le cas : exécutez vous-même une fois la commande de schéma ou de seed.
• « The database has no accounts, so nobody can sign in » signifie que les tables existent mais qu'aucun compte n'a jamais été ajouté : exécutez yarn seed dans back-end/.

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 de données vide, indiquez son nom dans DB_DATABASE dans back-end/.env, puis exécutez yarn seed (ou yarn db:sync pour les tables sans la boutique 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 exécutée avant le premier démarrage.

• Utiliser MySQL au lieu de SQLite

La connexion échoue

• Vérifiez le compte et l'application. Les comptes du personnel se connectent au tableau de bord admin sur le port 3031 : admin@example.com avec Admin@123. Les clients se connectent à la boutique sur le port 3030 : john.doe@example.com avec password123.
• Vérifiez le journal de l'API. « The database has no accounts, so nobody can sign in » signifie que la boutique de démonstration n'a jamais été ajoutée. Sans Docker, exécutez yarn seed dans back-end/. Avec Docker, le volume a été créé avec SEED_DEMO_DATA=false.
• « The database has no tables yet » signifie que le schéma n'a jamais été créé : exécutez yarn seed dans back-end/ et redémarrez l'API.
• Vous avez changé le mot de passe du Super Admin et ne l'avez plus : repartez de données de démonstration neuves, comme indiqué ci-dessous.
• « That email and password combination didn't work. Please try again. » est la même réponse pour un e-mail inconnu et pour un mauvais mot de passe : vérifiez donc les deux.
• « Too many attempts. Wait a minute and try again. » signifie qu'une même adresse a fait plus de 10 tentatives sur une route de connexion ou de mot de passe en une minute. Attendez une minute et réessayez.

La connexion échoue

• Vérifiez le journal de l'API. « The database has no accounts, so nobody can sign in » signifie que la boutique de démonstration n'a jamais été ajoutée : exécutez yarn seed, ou démarrez le conteneur Docker avec -e SEED_DEMO_DATA=true sur un nouveau volume.
• « The database has no tables yet » signifie que le schéma n'a jamais été créé : exécutez yarn seed et redémarrez l'API.
• Vérifiez le compte et la route. Le personnel se connecte via POST /api/auth/login (le Super Admin est admin@example.com avec Admin@123) ; les clients via POST /api/auth/customer/login (john.doe@example.com avec password123). Une connexion échouée répond 401 avec le même message, que ce soit l'e-mail ou le mot de passe qui soit faux.
• Une réponse `429` signifie qu'une même adresse a fait plus de 10 tentatives sur une route de connexion, d'inscription, de mot de passe ou de suivi de commande en une minute. L'en-tête Retry-After indique combien de secondes attendre.

La connexion échoue

Avec la boutique d'exemple, n'importe quel e-mail et mot de passe vous connectent à la boutique, et n'importe quel e-mail valide avec un mot de passe d'au moins 6 caractères au tableau de bord. Une fois une API connectée, connectez-vous avec un compte qui y existe : le Super Admin de démonstration est admin@example.com avec Admin@123, et le client de démonstration john.doe@example.com avec password123.

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

La connexion, l'inscription, la réinitialisation du mot de passe et le suivi de commande sans compte acceptent 10 requêtes par minute par adresse et par route, puis répondent 429. La cabine d'essayage compte aussi par adresse. L'API ne lit l'adresse du visiteur dans X-Forwarded-For que lorsque la requête vient d'un proxy sur une adresse privée, de loopback ou de la plateforme, comme sur Railway ou derrière Caddy ou nginx sur la même machine.

Quand votre proxy joint l'API depuis une adresse publique, chaque visiteur ressemble à ce seul proxy et tous partagent le même quota. Indiquez à l'API combien de proxies se trouvent devant elle :

TRUST_PROXY=1

TRUST_PROXY=false ne lit jamais l'en-tête. Laissez-la non définie quand l'API est jointe directement ou via un proxy sur une adresse privée. Les compteurs vivent dans la mémoire de l'API : un redémarrage les remet donc à zéro.

Une mention « Sample data » apparaît

Le frontend fonctionne sur sa boutique d'exemple intégrée au lieu de l'API, parce qu'il a été démarré ou construit sans NEXT_PUBLIC_API_BASE_URL. Ce que vous modifiez est alors conservé dans le navigateur, pas dans la base de données, et aucune commande n'est débitée.

1. 01

   Donnez au frontend l'adresse de l'API

   Créez le .env du frontend à partir de .env.example s'il n'en a pas. NEXT_PUBLIC_API_BASE_URL doit être l'adresse de l'API, /api compris, par exemple http://localhost:8000/api.
2. 02

   Vérifiez que l'API répond

   Ouvrez localhost:8000/api/healthLocal. Elle doit répondre {"status":"ok"}. Si l'adresse est définie mais que l'API ne répond pas, les pages ne peuvent pas charger leurs données : la boutique d'exemple ne prend pas le relais.
3. 03

   Redémarrez ou reconstruisez le frontend

   L'adresse est compilée dans l'application. Redémarrez yarn dev après l'avoir modifiée, relancez yarn build avant yarn start, ou avec Docker relancez docker compose up --build.

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.

Une fonctionnalité indique qu'elle n'est pas configurée

Les paiements par carte, les envois de fichiers, l'assistant IA, le studio IA, la suppression d'arrière-plan et la cabine d'essayage ne s'activent que lorsque leurs clés sont dans back-end/.env. La cabine d'essayage, le studio et la suppression d'arrière-plan ont aussi besoin du bucket de médias. Une clé qui garde exactement sa valeur de .env.example compte comme non définie : un .env.example copié démarre donc proprement, et chacune de ces fonctionnalités s'affiche comme désactivée au lieu d'échouer à son premier appel.

• Collez votre vraie clé à la place de la valeur d'exemple, pas à côté.
• Redémarrez l'API après avoir modifié back-end/.env. Avec Docker Compose, l'API lit aussi ce fichier : relancer docker compose up suffit donc ; un conteneur API seul a besoin de --env-file .env dans son docker run.

• Variables d'environnement

Les envois de fichiers répondent 503

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

Chaque envoi depuis le tableau de bord (photos de produits, avatars, pièces jointes de conversation, résultats du studio IA) va dans un bucket Cloudflare R2 ou autre bucket compatible S3, et répond 503 tant que les cinq variables R2_* ne sont pas définies dans back-end/.env. La cabine d'essayage, le studio et la suppression d'arrière-plan ont aussi besoin du bucket, et restent désactivés sans lui. La boutique de démonstration n'a pas besoin de bucket : ses images sont servies depuis des copies livrées avec les deux frontends dans public/mock-media/.

• Stockage des médias

Les images envoyées se chargent lentement ou en taille réelle

Les frontends ne redimensionnent et ne compressent que les images provenant d'hôtes qu'ils ont été construits pour accepter. Une image de votre bucket sur un autre hôte s'affiche quand même, mais sans optimisation.

1. 01

   Indiquez l'hôte public de votre bucket

   Sans Docker, définissez NEXT_PUBLIC_MEDIA_HOSTNAME dans le .env de chaque frontend avec l'hôte de R2_PUBLIC_URL, par exemple pub-1234.r2.dev. Avec Docker Compose, placez MEDIA_HOSTNAME=pub-1234.r2.dev dans un fichier .env à côté de docker-compose.yml. N'écrivez que l'hôte, sans https:// ni barre oblique finale.
2. 02

   Recompilez les frontends

   L'hôte est compilé dans l'application. Redémarrez yarn dev et reconstruisez pour la production, ou relancez docker compose up --build.

Les requêtes sont bloquées sur vos propres domaines

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

L'API ne répond aux navigateurs que depuis les adresses de CORS_ORIGIN, et les notifications en direct du tableau de bord admin que depuis FRONTEND_URL. Les deux valent par défaut les deux ports locaux : sur vos propres domaines, elles doivent donc indiquer vos sites.

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

Écrivez chaque adresse exactement comme le navigateur l'affiche, avec https:// et sans barre oblique finale, puis redémarrez l'API. Avec Docker Compose, définissez plutôt SITE_URL, ADMIN_URL et API_URL dans le .env à côté de docker-compose.yml et exécutez docker compose up --build : le fichier compose construit les deux listes à partir d'eux.

• Mise en ligne

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 back-end/Dockerfile livré les supprime pendant le build : ce problème n'apparaît donc 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.

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

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 données de démonstration neuves

Avec Docker Compose, depuis le dossier e-commerce-1 :

docker compose down -v
docker compose up

Avec un conteneur API seul, supprimez d'abord le conteneur (docker ps -a l'affiche, docker rm -f suivi de son identifiant le supprime), puis supprimez le volume et relancez-le :

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

Sans Docker, arrêtez l'API, puis :

rm -f database.sqlite* && yarn seed

Dans PowerShell :

Remove-Item database.sqlite*; yarn seed

Relancer yarn seed sur une base de données que vous conservez n'est pas une réinitialisation : la commande n'ajoute que ce qui manque et ne remet jamais à zéro une valeur que vous avez modifiée dans le tableau de bord. Sur MySQL, yarn db:reset supprime toutes les tables avant yarn seed.

Repartir de la boutique d'exemple

Sans API, vos modifications sont conservées dans le navigateur. Pour retrouver la boutique d'exemple, exécutez ceci dans la console du navigateur, sur la page de l'application :

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