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 une exécution précédente de Hollina, 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 l'exécution précédente : Ctrl+C dans son terminal, docker compose down dans son dossier, ou docker stop pour un conteneur lancé avec docker run. Puis redémarrez Hollina.
3. 03

   Ou lancer Hollina sur d'autres ports

   Avec la pile complète dans Docker, créez un fichier nommé .env dans le dossier hollina-vacation-rental-full-stack, à côté de docker-compose.yml, avec le port dont vous avez besoin. SITE_PORT déplace le site, ADMIN_PORT le tableau de bord et API_PORT l'API ; les adresses que les applications utilisent, CORS_ORIGIN compris, suivent d'elles-mêmes.

   hollina-vacation-rental-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 hollina-vacation-rental-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 en général en train de charger le seed de la société de démonstration. Le site et le tableau de bord 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 (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 booking 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 aucun séjour 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 de données 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 séjour ni compte pour se connecter.

• Sans Docker : lancez yarn seed dans le dossier de l'API. Il ajoute la société de démonstration et ses comptes aux tables que vous avez.
• 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 la société 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@hollina.example avec Admin@123, ou manager@hollina.example avec Manager@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 de données n'a aucun compte quand elle a été créée avec SEED_DEMO_DATA=false. Voir Le site n'a aucun séjour et personne ne peut se connecter, ci-dessus.
• « Too many attempts. Please try again later » Dix connexions échouées depuis une même adresse en 15 minutes verrouillent le formulaire pour cette adresse jusqu'à ce que l'échec le plus ancien 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 suivant.
• 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@hollina.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 de données a été créée sans la société 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 Hollina, donc le compte doit y exister. Sur une API avec seed, connectez-vous avec admin@hollina.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 affichent « Something went wrong. Try again. »

Something went wrong. Try again.
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, et SITE_URL celle du site, où un processeur de paiement renvoie le voyageur. Déplacez chacune avec son application.
• 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 séjour affiche « Stay » dans Docker

Le serveur propre du site lit le titre du séjour pour l'onglet du navigateur, le premier rendu de l'accueil et des pages de séjour, et le sitemap. Dans un conteneur, localhost désigne le conteneur lui-même, donc ce serveur ne peut 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 hollina-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 photographies des séjours ne se chargent pas

Les photographies du seed sont servies par l'API sur /media/hollina/…, et chaque adresse de photographie est construite à partir de PUBLIC_MEDIA_URL, qui vaut http://localhost:8000/media par défaut. Une photographie est cassée quand cette adresse n'atteint 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 été déplacée après le premier démarrage. Redémarrez-la avec le nouveau PUBLIC_MEDIA_URL : au démarrage, elle fait pointer chaque photographie enregistrée vers cette adresse, et son journal affiche « 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 photographies se chargent, mais en pleine taille. Les frontends ne redimensionnent que les photographies des hôtes https de NEXT_PUBLIC_MEDIA_HOSTNAME (avec Docker Compose, MEDIA_HOSTNAME), chacun écrit seul et séparé par des virgules, comme api.your-company.com,pub-1234.r2.dev. Toute autre photographie, comme celle d'une API sur localhost, se charge telle quelle. Reconstruisez le frontend après l'avoir modifié.

• Variables d'environnement

La page d'un séjour affiche « The map could not be loaded. »

La carte tire ses tuiles d'OpenFreeMap par défaut, elle a donc besoin d'un accès à internet, et le service ne promet aucune disponibilité. Vérifiez la connexion, ou définissez NEXT_PUBLIC_MAP_STYLE_LIGHT (et NEXT_PUBLIC_MAP_STYLE_DARK pour le thème sombre) avec le style MapLibre d'un autre fournisseur et reconstruisez le site.

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 réservation payée reste en attente

We are confirming your payment.
This is taking longer than usual.

Ce qui confirme une réservation par carte ou PayPal, c'est le webhook du processeur, jamais le retour du voyageur sur le site. Tant qu'il n'est pas arrivé, la page de réservation attend, la réservation reste pending et retient ses nuits pendant 30 minutes, puis un nettoyage l'annule comme expirée.

• Stripe : STRIPE_WEBHOOK_SECRET est absent ou faux, donc chaque webhook Stripe est refusé. En local, lancez stripe listen --forward-to localhost:8000/api/webhooks/payments/stripe, placez le secret qu'il affiche dans le .env de l'API et redémarrez l'API. Sur un serveur, créez l'endpoint dans Stripe à l'adresse publique de votre API.
• PayPal : la page de retour capture la commande par POST /api/bookings/:reference/settle ; le webhook a besoin de PAYPAL_WEBHOOK_ID, l'identifiant d'un abonnement à PAYMENT.CAPTURE.COMPLETED sur /api/webhooks/payments/paypal.
• stripe trigger checkout.session.completed ne confirme rien : un événement déclenché ne porte aucune référence de réservation. Terminez plutôt un vrai paiement de test dans le navigateur, avec la carte 4242 4242 4242 4242.

• Réservations et paiements

Une réservation, une question ou un avis est refusé

Your payment was declined. Try another card or another way to pay.
That payment method is not available. Choose another way to pay.
Too many requests were sent from this connection. Please wait a few minutes and try again.
The selected dates do not meet the minimum stay.

• Refusé : sans processeur, le simulateur fourni refuse un numéro de carte se terminant par 0, exprès, pour que le cas d'échec soit visible. Tout autre numéro est accepté.
• Moyen de paiement indisponible : l'API n'accepte plus ce moyen, comme PayPal quand seul Stripe est configuré, la carte quand seul PayPal l'est, ou le paiement à l'arrivée après la désactivation de son interrupteur. Rien n'a été écrit et aucune nuit n'est retenue : rechargez le paiement, qui ne propose alors que ce que l'API accepte.
• Une question ou un avis est refusé : le message d'une question compte de 10 à 4000 caractères et le commentaire d'un avis de 10 à 2000, et le formulaire l'indique sous le champ avant l'envoi.
• Trop de requêtes : chaque adresse peut envoyer cinq réservations, cinq questions et cinq avis en dix minutes. Pendant vos tests, attendez, ou redémarrez l'API : les compteurs sont dans sa mémoire.
• Dates refusées : un séjour a son propre nombre minimal de nuits et son maximum de voyageurs, une arrivée ne peut pas être dans le passé, et les nuits que retient une autre réservation ou un blocage sont prises. Les réservations couvrent [check-in, check-out), donc un voyageur peut arriver le jour où un autre repart.
• Annulation en ligne refusée : un voyageur annule depuis sa page de réservation tant qu'elle est en attente ou confirmée et que l'arrivée est dans au moins sept jours ; après, la page dit de contacter l'hôte, qui peut encore annuler depuis le tableau de bord.
• 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 paiement, le formulaire de question et celui d'avis sont limités par adresse de visiteur. Derrière un reverse proxy, chaque visiteur peut sembler avoir l'unique adresse du proxy et partager un seul quota. Indiquez à l'API combien de proxies 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.

L'assistant indique qu'il n'est pas encore connecté

The assistant is not connected yet. Add a Google Gemini key as GOOGLE_API_KEY in the API's .env file, restart the API, then ask again.

L'assistant répond uniquement avec Google Gemini, sur la clé de GOOGLE_API_KEY dans le .env de l'API. Dans .env.example, cette ligne est en commentaire, donc un fichier copié démarre proprement avec l'assistant désactivé et rien de facturé.

• Retirez le # devant GOOGLE_API_KEY, collez votre vraie clé de Google AI Studio à 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.

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

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

Google a refusé la requête parce que le quota de la clé pour ce modèle est épuisé pour le moment, ou que le modèle n'a pas de capacité à cet instant, et le message nomme le modèle. L'assistant 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. Choisissez un autre modèle dans la liste au-dessus du chat, ou attendez quelques minutes, puis appuyez sur Try again. Les quotas sont comptés par modèle, donc un autre répond souvent encore.

En mode démo, l'assistant demande la clé propre du visiteur

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:  hollina-…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 hollina-vacation-rental-full-stack :

docker compose down -v
docker compose up

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

docker volume rm hollina-api-data
docker run -p 8000:8000 -v hollina-api-data:/data -e SEED_DEMO_DATA=true hollina-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 gardez n'est pas une réinitialisation : il ne réinitialise jamais un mot de passe et n'ajoute rien en double, il remet les séjours, réservations et paramètres de société fournis à leurs valeurs d'origine, et il garde les séjours, réservations et autres lignes que vous avez créés. yarn db:reset supprime chaque table, sur SQLite comme sur MySQL ; lancez yarn seed ensuite.