LANTORIANDocker, pas à pas

Chapitre 1015 min

Dépannage

Une erreur n'est pas un mur, c'est un message. Voici comment le lire, et les solutions aux problèmes que tout le monde rencontre.

La méthode

Dans cet ordre, avant de demander de l'aide.

  1. Quel service est tombé ? docker compose ps. Un état Exited ou Restarting désigne le coupable.
  2. Que dit-il ? docker compose logs --tail=50 service. La cause est presque toujours dans les dernières lignes.
  3. Que voit-il ? docker compose exec service sh, puis vérifie les variables (env), les fichiers (ls) et le réseau (getent hosts db).
  4. Repartir propre. docker compose down puis docker compose up -d --build.

Erreurs fréquentes

Clique sur le message qui ressemble au tien.

port is already allocated

Le port de gauche de ports: est déjà pris, souvent par un autre projet Docker ou un service local.

Terminal
docker ps --format "{{.Names}} {{.Ports}}"   # qui utilise le port ?
sudo lsof -i :8000                            # hors Docker (Linux, macOS)

Arrête l'autre projet, ou change le port de gauche : "8001:80".

permission denied while trying to connect to the Docker daemon socket

Sur Linux, ton utilisateur n'est pas dans le groupe docker (voir le chapitre 2). Sinon, Docker n'est pas démarré : ouvre Docker Desktop, ou lance sudo systemctl start docker.

could not translate host name "db" / Connection refused
  • Tu as lancé php artisan sur ta machine au lieu du conteneur. Utilise docker compose exec php php artisan ....
  • DB_HOST vaut 127.0.0.1 dans api/.env. Il doit valoir db.
  • Laravel a gardé l'ancienne configuration en cache : docker compose exec php php artisan config:clear.
storage/logs/laravel.log could not be opened: Permission denied

L'utilisateur de PHP-FPM n'a pas le même identifiant que toi. Vérifie id -u, mets la bonne valeur dans le .env racine, puis :

Terminal
docker compose build --no-cache php
docker compose up -d
docker compose exec php chmod -R ug+rw storage bootstrap/cache
502 Bad Gateway / File not found.
  • 502 : nginx n'arrive pas à joindre PHP. Le service php est-il démarré ? fastcgi_pass vaut-il bien php:9000 ?
  • File not found. : nginx et php ne montent pas le code au même chemin, ou root ne pointe pas vers /var/www/html/public.
TypeError: fetch failed (ECONNREFUSED 127.0.0.1:8000)

Un Server Component appelle localhost:8000. Dans le conteneur front, localhost désigne le conteneur lui-même. Utilise API_URL_INTERNAL=http://nginx côté serveur (chapitre 9).

Mes modifications n'apparaissent pas
  • Tu as modifié un Dockerfile : il faut reconstruire avec docker compose up -d --build.
  • Tu as modifié compose.yaml ou un .env : docker compose up -d recrée les conteneurs concernés. restart ne suffit pas.
  • Le rechargement à chaud de Next.js ne réagit pas : projet dans /mnt/c sous Windows, ou ajoute WATCHPACK_POLLING: "true" au service.
Cannot find module ... / Class ... not found

Une dépendance a été ajoutée mais pas installée dans le conteneur. Côté PHP : docker compose exec php composer install. Côté Next.js, recrée le volume des modules :

Terminal
docker compose rm -sf front
docker volume rm projet_front-modules   # préfixe = nom du dossier
docker compose up -d front
Mes données ont disparu après un redémarrage

Soit tu as lancé docker compose down -v, soit le volume n'est pas monté au bon chemin. Pour PostgreSQL 18 : /var/lib/postgresql. Pour les versions 17 et antérieures : /var/lib/postgresql/data.

no space left on device

Docker garde images, caches de build et volumes orphelins. Voir la section suivante.

Libérer de l'espace disque

Docker ne supprime rien tout seul. Fais le ménage de temps en temps.

Terminal
docker system df          # ce qui prend de la place
docker image prune        # images sans tag
docker builder prune      # cache de build
docker container prune    # conteneurs arrêtés
Échap