Échecs au démarrage

Le conteneur de l’application applique ses migrations puis commence à répondre, et il s’arrête de lui-même plutôt que de tourner avec un schéma ou une configuration qui ne lui correspondent pas. Docker le redémarre aussitôt, si bien qu’une pile mal configurée semble fonctionner : docker compose ps affiche toujours l’application en Up, avec son contrôle de santé à starting, car le conteneur ne vit jamais assez longtemps pour échouer à ce contrôle.

Consultez plutôt le journal :

docker compose logs app | tail -30

Deux échecs absents du journal

Si le .env contient encore un secret vide, la pile ne démarre même pas : docker compose up refuse d’interpréter le fichier et affiche required variable SECRET_ENCRYPTION_KEY is missing a value: empty in .env; fill it with openssl rand -base64 32. Il signale toutes les variables vides d’un coup plutôt qu’une à chaque lancement : un .env copié sans être modifié les affiche donc toutes les trois en même temps, et POSTGRES_PASSWORD deux fois, parce que les deux services la lisent. Remplissez-les et relancez la commande ; rien n’est construit tant qu’il en manque une.

Un port déjà occupé arrête tout aussi tôt. docker compose up construit l’image, démarre la base, puis affiche failed to bind host port 0.0.0.0:8080/tcp: address already in use et s’arrête là. Le conteneur de l’application a été créé mais jamais démarré : docker compose logs app n’affiche donc rien, et docker compose ps ne montre que la base. Choisissez un port libre pour WEB_PORT dans .env, reportez-le dans PUBLIC_URL, et relancez la commande.

Une pile à moitié démarrée

Ce second échec laisse une pile à moitié démarrée, sans que rien ne le signale. Compose démarre d’abord la base, puis l’application, et il n’arrête pas la base quand l’application ne démarre pas : la commande se termine avec le code 1 en ne citant que le conteneur qui a échoué, et la base continue de tourner.

docker compose ps      # ce qui a survécu à l'échec : la base, sans l'application

Le conteneur de l’application subsiste lui aussi, sans réseau : il a été créé mais jamais démarré, car c’est son raccordement au réseau par Docker qui a échoué. Compose démarre un conteneur existant plutôt que d’en créer un nouveau : si vous libérez le port à la main et relancez le même up, c’est ce conteneur-là qui démarre. Il n’a aucun accès à la base et boucle sur P1001: Can't reach database server at db:5432, alors que la base tourne juste à côté.

Changer WEB_PORT et PUBLIC_URL évite ce piège, car c’est une modification du .env qui pousse Compose à remplacer le conteneur. Si vous préférez libérer le port, nettoyez d’abord la pile à moitié démarrée :

docker compose down    # conteneurs et réseau partis ; le volume et ses données ne sont pas touchés

Seul down -v efface les données de la base.

Cinq messages du journal

Ce que dit le journal	Ce que cela signifie
`Invalid environment configuration:`	une variable manque ou est mal formée ; la ligne suivante indique laquelle et la commande à lancer
`SECRET_ENCRYPTION_KEY: must be 32 bytes base64-encoded`	`openssl rand -hex 32` donne 48 octets une fois décodé, pas 32 ; il faut `openssl rand -base64 32` pour cette clé
`DATABASE_URL: is not a valid connection URL`	`POSTGRES_PASSWORD` contient un `/`, un `?` ou un `#`, que l’URL de connexion prend pour ses propres séparateurs
`P1001: Can't reach database server`	la base n’avait pas encore démarré, en général après un redémarrage de la machine ; tout rentre dans l’ordre en quelques secondes
`P1000: Authentication failed against database server`	`POSTGRES_PASSWORD` a été modifié après le premier démarrage ; la base attend toujours l’ancien

Dans ce dernier cas, la solution est de remettre l’ancien mot de passe.