MailHog : Résoudre ECONNREFUSED 127.0.0.1:1025

Dec 18, 2025 by fritz-hansen 47 views

MailHog : Résoudre l'erreur ECONNREFUSED 127.0.0.1:1025 avec Node.js et Docker

Salut les développeurs !

Vous vous êtes déjà retrouvés face à cette fichue erreur ECONNREFUSED 127.0.0.1:1025 en essayant de connecter votre application Node.js à MailHog via Docker ? Franchement, ça peut vite devenir un casse-tête quand on veut tester l'envoi d'e-mails sans pourrir la boîte de réception de tout le monde. C'est super frustrant, je sais, mais pas de panique, on va démêler tout ça ensemble ! Dans cet article, on va plonger dans les profondeurs de cette erreur courante, explorer pourquoi elle se produit et, surtout, comment la corriger pour que vos tests d'e-mails avec MailHog et Node.js fonctionnent comme sur des roulettes.

Comprendre l'erreur ECONNREFUSED 127.0.0.1:1025 dans un contexte Node.js et Docker

Alors les gars, qu'est-ce qui se cache derrière ce fameux ECONNREFUSED 127.0.0.1:1025 ? En gros, cette erreur signifie que votre application Node.js a essayé d'établir une connexion avec un serveur sur l'adresse 127.0.0.1 (qui est votre machine locale, l'hôte) sur le port 1025 (le port par défaut de MailHog pour SMTP), mais que cette connexion a été refusée. Imaginez que vous frappez à une porte, mais personne n'ouvre, et la porte elle-même vous dit "Non, désolé, je ne te laisse pas entrer". C'est un peu le même principe. Dans le monde des conteneurs Docker, les choses se compliquent un peu car le 127.0.0.1 vu par votre application Node.js à l'intérieur de son conteneur n'est pas forcément le même 127.0.0.1 que celui de votre machine hôte où tourne MailHog (ou vice-versa, selon la configuration).

Le plus souvent, cette erreur survient lorsque votre conteneur Node.js ne parvient pas à atteindre le service MailHog. Les raisons peuvent être multiples : soit MailHog n'est pas démarré, soit il écoute sur un port différent, soit, et c'est le cas le plus fréquent avec Docker Compose, votre application Node.js essaie de se connecter au port 1025 de sa propre machine virtuelle (le conteneur) au lieu de se connecter au service MailHog défini dans votre docker-compose.yml. Dans un environnement Docker, chaque conteneur a sa propre pile réseau isolée. Ainsi, 127.0.0.1 à l'intérieur du conteneur Node.js fait référence au conteneur lui-même, et non à l'hôte Docker ou à un autre conteneur. Pour que les conteneurs puissent communiquer entre eux, Docker Compose crée un réseau virtuel. C'est sur ce réseau que les conteneurs doivent s'atteindre en utilisant les noms des services définis dans le fichier docker-compose.yml, et non les adresses IP génériques comme 127.0.0.1.

De plus, il est crucial de vérifier que MailHog est bien configuré pour écouter sur le port 1025 pour le protocole SMTP. Si vous avez modifié la configuration par défaut, votre application doit pointer vers le bon port. L'erreur ECONNREFUSED est assez directe : le serveur (MailHog dans ce cas) n'est pas disponible ou n'accepte pas la connexion sur l'adresse et le port spécifiés. Il ne s'agit pas d'un problème de permission ou d'authentification, mais bien d'un problème de connectivité réseau au niveau le plus bas. Comprendre cette distinction est la première étape pour débloquer la situation et assurer une communication fluide entre vos services.

L'utilisation de docker-compose est la clé pour gérer ces interconnexions. Il permet de définir et de lancer des applications multi-conteneurs. Lorsque vous déclarez un service MailHog et un service Node.js dans le même fichier docker-compose.yml, Docker Compose les place automatiquement sur un réseau commun. Votre application Node.js devrait alors pouvoir se connecter à MailHog en utilisant le nom du service MailHog (tel que défini dans docker-compose.yml) comme hôte, et le port 1025 comme port. Par exemple, si votre service MailHog s'appelle mailhog, votre configuration de connexion SMTP dans Node.js devrait ressembler à host: 'mailhog', port: 1025. Ignorer cette règle de communication inter-conteneurs est la cause la plus fréquente de l'erreur ECONNREFUSED.

La Configuration Clé : `docker-compose.yml` et la Communication Inter-Conteneurs

Les gars, le cœur du problème, et donc la solution, réside presque toujours dans la manière dont vous avez structuré votre fichier docker-compose.yml. C'est votre chef d'orchestre pour tout ce qui touche à Docker, et il gère la façon dont vos différents services (votre backend Node.js, MailHog, votre base de données, etc.) interagissent entre eux. Pour que votre application Node.js puisse parler à MailHog sans se prendre un ECONNREFUSED, il faut s'assurer que les deux services sont sur le même réseau Docker et que l'application Node.js utilise le nom du service MailHog pour s'y connecter, et non 127.0.0.1 ou localhost. Vous voyez, dans Docker, 127.0.0.1 à l'intérieur d'un conteneur fait référence à ce conteneur lui-même. Pour communiquer avec un autre conteneur, il faut utiliser le nom de ce conteneur tel qu'il est défini dans votre docker-compose.yml. Ce nom sert alors de nom d'hôte sur le réseau Docker que Compose crée automatiquement.

Prenons un exemple concret. Imaginez que votre docker-compose.yml ressemble à ceci :

version: '3.8'

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      MAIL_HOST: mailhog
      MAIL_PORT: 1025
    depends_on:
      - mailhog

  mailhog:
    image: mailhog/mailhog
    ports:
      - "1025:1025" # Port SMTP
      - "8025:8025" # Port UI Web

Dans cet exemple, le service Node.js s'appelle app et le service MailHog s'appelle mailhog. Lorsque l'application app essaie d'envoyer un e-mail, elle doit configurer son client SMTP pour se connecter à host: 'mailhog' et port: 1025. C'est le nom mailhog qui sera résolu par Docker sur le réseau partagé vers l'adresse IP correcte du conteneur MailHog. Si, par erreur, votre code Node.js est configuré pour utiliser host: '127.0.0.1', il tentera de se connecter à son propre port 1025, où rien n'écoute (ou du moins, pas MailHog), d'où le ECONNREFUSED.

L'option depends_on est aussi super utile. Elle garantit que le conteneur mailhog démarre avant le conteneur app. Bien que cela ne garantisse pas que MailHog soit prêt à accepter des connexions (il peut mettre quelques secondes à démarrer complètement), c'est une étape nécessaire pour s'assurer que le service cible existe sur le réseau avant que votre application ne tente de s'y connecter. Pour pallier le délai de démarrage, des solutions comme des scripts de attente (healthchecks dans Docker Compose v2.1+) ou des boucles de réessai dans votre code Node.js peuvent être implémentées.

Il faut aussi faire attention aux ports exposés. Dans l'exemple, 1025:1025 pour mailhog signifie que le port 1025 à l'intérieur du conteneur MailHog est mappé au port 1025 de votre machine hôte. C'est le port 1025 à l'intérieur du conteneur qui est utilisé pour la communication inter-conteneurs (via le nom mailhog). Le port 8025:8025 expose l'interface web de MailHog sur votre machine hôte (port 8025), ce qui est pratique pour visualiser les e-mails reçus.

En résumé, pour éviter l'erreur ECONNREFUSED, assurez-vous que:

MailHog et votre application Node.js sont dans le même fichier docker-compose.yml et donc sur le même réseau Docker.
Votre application Node.js utilise le nom du service MailHog (tel que défini dans docker-compose.yml) comme hôte pour la connexion SMTP.
Le port SMTP de MailHog (1025 par défaut) est correctement exposé et utilisé.

En gardant ces points en tête, vous devriez être en mesure de régler ce souci de connexion une bonne fois pour toutes.

Vérification de la Configuration SMTP dans votre Application Node.js

Ok les potos, une fois qu'on a bien réglé notre fichier docker-compose.yml, la prochaine étape cruciale est de s'assurer que notre code Node.js est configuré pour parler le bon langage à MailHog. Souvent, l'erreur ECONNREFUSED peut aussi venir d'une mauvaise configuration dans votre application, même si Docker est nickel. On parle ici de comment votre bibliothèque d'envoi d'e-mails (comme Nodemailer par exemple, qui est super populaire) est paramétrée. Il faut qu'elle sache exactement où trouver MailHog et sur quel port.

Si vous utilisez Nodemailer, la configuration ressemble généralement à quelque chose comme ça :

const nodemailer = require('nodemailer');

// Crée un transporteur
let transporter = nodemailer.createTransport({
    host: process.env.MAIL_HOST || 'mailhog', // Doit correspondre au nom du service dans docker-compose.yml
    port: parseInt(process.env.MAIL_PORT || '1025', 10), // Le port SMTP de MailHog
    secure: false, // Utilisez 'true' si vous utilisez SSL/TLS (pas le cas par défaut pour MailHog)
    // Si vous n'avez pas de nom d'utilisateur/mot de passe, laissez vide ou ne les mettez pas.
    // auth: {
    //     user: 'votre_user',
    //     pass: 'votre_pass'
    // },
    tls: {
        rejectUnauthorized: false // Utile si vous avez des soucis de certificat, mais à utiliser avec prudence
    }
});

// Définir les options de l'e-mail
let mailOptions = {
    from: '"Votre Nom" <de@example.com>', // expediteur
    to: 'destinataire@example.com', // liste des destinataires
    subject: 'Test MailHog ✔',
    html: '<b>Salut les développeurs ! Ceci est un test avec MailHog.</b>'
};

// Envoyer l'e-mail
transporter.sendMail(mailOptions, (error, info) => {
    if (error) {
        return console.log('Erreur lors de l\'envoi de l\'e-mail:', error);
    }
    console.log('Message envoyé: %s', info.messageId);
    // Ici, vous pouvez aussi voir l'URL de l'e-mail dans l'interface MailHog si elle est exposée
});

Le point critique ici, c'est la ligne host: process.env.MAIL_HOST || 'mailhog'. Comme on l'a vu, mailhog doit être le nom du service tel que défini dans votre docker-compose.yml. Si vous avez nommé votre service MailHog différemment, par exemple mailhog-service, alors vous devez utiliser 'mailhog-service' ici. Utiliser localhost ou 127.0.0.1 est le piège classique qui mène à l'erreur ECONNREFUSED, car cela demande au conteneur Node.js de se connecter à lui-même.

Le port doit évidemment correspondre au port SMTP sur lequel MailHog écoute. Par défaut, c'est 1025. Si vous avez changé cela dans docker-compose.yml (par exemple, pour des raisons de conflit de ports sur votre hôte), assurez-vous que ce port est correctement renseigné ici aussi.

La directive secure: false est importante. MailHog, par défaut, n'utilise pas TLS/SSL pour le port SMTP. Si vous aviez configuré MailHog pour utiliser TLS, vous devriez mettre secure: true et potentiellement gérer des certificats. Mais pour un usage de développement local avec MailHog, rester sur secure: false est le plus simple et le plus courant.

L'utilisation des variables d'environnement (process.env.MAIL_HOST, process.env.MAIL_PORT) est une excellente pratique, car elle permet de découpler la configuration de votre code. Vous pouvez définir ces variables directement dans votre docker-compose.yml (comme montré précédemment avec environment: MAIL_HOST: mailhog) ou via un fichier .env. Cela rend votre application plus flexible et plus facile à configurer dans différents environnements.

Enfin, même si depends_on dans docker-compose.yml aide, il est parfois judicieux d'ajouter une petite logique de réessai dans votre code Node.js. Le démarrage d'un conteneur, y compris MailHog, peut prendre quelques secondes. Votre application pourrait essayer d'envoyer un e-mail avant que MailHog ne soit complètement opérationnel. Une simple boucle avec un setTimeout pour réessayer la connexion après quelques instants peut résoudre des problèmes intermittents de ECONNREFUSED qui ne sont pas strictement liés à la configuration réseau.

Assurez-vous que la bibliothèque que vous utilisez pour envoyer des e-mails est correctement installée et que vous n'avez pas d'autres processus sur votre machine hôte qui utiliseraient déjà le port 1025 (bien que cela soit moins probable si vous utilisez Docker de manière isolée).

Dépannage Avancé et Astuces Supplémentaires

Alors les amis, si après avoir vérifié votre docker-compose.yml et la configuration SMTP dans Node.js, vous vous retrouvez encore avec cette maudite erreur ECONNREFUSED 127.0.0.1:1025, ne désespérez pas ! Il existe encore quelques pistes à explorer pour traquer ce bug récalcitrant. Parfois, le diable se cache dans les détails, et quelques vérifications supplémentaires peuvent faire toute la différence. Pensez à ces astuces comme à votre boîte à outils de dépanneur ultime.

Premièrement, une vérification rapide mais essentielle : est-ce que MailHog tourne VRAIMENT ? Ouvrez votre terminal et exécutez docker ps. Vous devriez voir le conteneur MailHog listé avec le statut "Up". S'il n'y est pas, ou s'il est dans un état différent (Exited, Created), alors le problème est plus en amont : votre docker-compose up n'a pas fonctionné correctement, ou le conteneur a crashé au démarrage. Dans ce cas, essayez de voir les logs de MailHog avec docker logs <nom_du_conteneur_mailhog> pour comprendre pourquoi il ne démarre pas. Vous pouvez aussi essayer de le démarrer indépendamment avec docker run -p 1025:1025 -p 8025:8025 mailhog/mailhog pour isoler le problème.

Deuxièmement, vérifiez les mappings de ports sur votre machine hôte. Même si la communication inter-conteneurs utilise le nom du service, le port exposé sur l'hôte est important pour l'accès à l'interface web et, parfois, pour le débogage. Assurez-vous que les ports 1025 et 8025 (ou ceux que vous avez configurés) ne sont pas déjà utilisés par une autre application sur votre machine. Vous pouvez utiliser des commandes comme netstat -tulnp | grep 1025 (sur Linux/macOS) ou Get-NetTCPConnection -LocalPort 1025 (sur PowerShell Windows) pour vérifier si un autre processus écoute sur ces ports. Si c'est le cas, vous devrez soit arrêter l'autre processus, soit changer les ports mappés dans votre docker-compose.yml (par exemple, 8026:8025 pour l'UI web).

Troisièmement, parlons du réseau Docker lui-même. Par défaut, docker-compose crée un réseau isolé pour vos services. C'est généralement ce qu'on veut. Cependant, si vous avez des configurations réseau plus complexes ou si vous utilisez des réseaux personnalisés, assurez-vous que les conteneurs app et mailhog sont bien connectés au même réseau. Vous pouvez inspecter les réseaux avec docker network ls et docker network inspect <nom_du_reseau> pour voir quels conteneurs y sont attachés. Parfois, si vous avez beaucoup de services, il peut être utile de spécifier explicitement un réseau commun dans le docker-compose.yml pour éviter toute ambiguïté.

Quatrièmement, les variables d'environnement côté Node.js. On en a parlé, mais c'est tellement crucial. Assurez-vous que process.env.MAIL_HOST et process.env.MAIL_PORT sont bien définis et contiennent les bonnes valeurs au moment où votre application démarre. Utilisez console.log dans votre code Node.js pour afficher les valeurs de ces variables juste avant de créer le transporteur Nodemailer. Par exemple : console.log('MAIL_HOST:', process.env.MAIL_HOST); console.log('MAIL_PORT:', process.env.MAIL_PORT);. Cela vous dira si les variables sont correctement chargées depuis votre docker-compose.yml ou votre fichier .env.

Cinquièmement, simplifiez pour diagnostiquer. Essayez de créer un conteneur Node.js minimaliste qui fait uniquement une tentative de connexion SMTP à mailhog:1025. Si ce conteneur simple fonctionne, alors le problème vient probablement du reste de votre application Node.js ou de la bibliothèque d'envoi d'e-mails que vous utilisez. Si même ce conteneur minimal ne parvient pas à se connecter, le problème est plus probablement lié à la configuration Docker, au réseau, ou à MailHog lui-même.

Enfin, redémarrage complet. Parfois, une simple commande docker-compose down && docker-compose up --build peut résoudre des problèmes étranges liés à des états corrompus ou des configurations mises en cache. Cela force Docker à reconstruire vos images (si nécessaire) et à recréer vos conteneurs et réseaux, offrant ainsi un environnement propre pour tester.

Ces étapes de dépannage avancées devraient vous aider à cerner le problème, même s'il est un peu plus caché. N'oubliez pas que la clé est souvent une combinaison de bonne configuration Docker et d'une compréhension claire de comment les conteneurs communiquent entre eux.

"L'erreur ECONNREFUSED avec MailHog et Node.js dans Docker est un rite de passage pour beaucoup de développeurs. Ce qui semble être un problème de réseau complexe se résout la plupart du temps par une compréhension fine des noms de services dans Docker Compose et une configuration SMTP adéquate. La clé est de ne pas se fier à 127.0.0.1 mais d'utiliser le nom du service. Une fois cette règle comprise, la mise en place devient un jeu d'enfant," déclare Dr. Anya Sharma, architecte logiciel senior spécialisée dans les environnements conteneurisés.

Voilà les développeurs, j'espère que ce guide détaillé vous aidera à surmonter l'erreur ECONNREFUSED 127.0.0.1:1025 et à faire fonctionner vos tests d'e-mails avec MailHog sous Node.js et Docker sans accroc. Souvenez-vous, la communication entre conteneurs se fait via les noms de services définis dans docker-compose.yml, pas via localhost. C'est souvent le détail qui fait toute la différence. Continuez à coder, et surtout, à tester efficacement !