Mailpit in WSL mit Docker Engine einrichten für lokale Projekte

Wer mehrere lokale Projekte in WSL betreibt, kennt das Problem: Jedes Projekt bringt schnell seine eigene Mail-Testlösung mit, oft per Docker Compose, manchmal direkt im Stack der Anwendung. Das funktioniert, erzeugt aber doppelte Container, mehr Pflegeaufwand und unnötige Unterschiede zwischen Projekten. Praktischer ist eine zentrale Mail-Sandbox, die dauerhaft läuft und von mehreren lokalen Anwendungen gemeinsam genutzt werden kann.

Genau dafür eignet sich Mailpit sehr gut. In diesem Beitrag richten wir Mailpit mit Docker Engine direkt in WSL ein und nutzen es als gemeinsame SMTP-Testinstanz für lokale Projekte. Optional binden wir die Weboberfläche zusätzlich per Apache unter mailpit.test ein. Wer unseren LAMP-Stack für Laravel auf WSL nachgearbeitet hat, kann diesen Teil direkt übernehmen.

Warum eine zentrale Mail-Testumgebung sinnvoll ist

Mailpit erfüllt in der lokalen Entwicklung einen einfachen Zweck: Anwendungen senden E-Mails nicht an echte Postfächer, sondern an einen Test-SMTP-Dienst. Dort lassen sich Nachrichten in einer Weboberfläche prüfen, ohne dass versehentlich echte Empfänger angeschrieben werden.

Wenn wir dafür pro Projekt eine eigene Instanz betreiben, wiederholen wir immer dieselbe Arbeit. Ein einzelner Mailpit-Container in WSL spart diesen Overhead. Nicht-containerisierte Anwendungen können in vielen Fällen direkt an 127.0.0.1:1025 senden. Die Oberfläche erreichen wir dann über http://localhost:8025.

Das Setup ist vor allem dann praktisch, wenn mehrere lokale PHP-, Laravel- oder andere Webprojekte parallel auf derselben WSL-Umgebung laufen. Bei komplett containerisierten Projekt-Stacks kann die Anbindung je nach Netzwerkaufbau anders aussehen. Dann ist 127.0.0.1 innerhalb eines Containers oft nicht der richtige Zielhost.

Voraussetzungen

Für die Grundvariante benötigen wir lediglich eine laufende WSL-Distribution auf Ubuntu- oder Debian-Basis sowie die Möglichkeit, Docker Engine darin zu installieren.

Für die optionale Domain mailpit.test per Apache Reverse Proxy wird zusätzlich ein lokaler Apache-Webstack in WSL benötigt. Die in diesem Beitrag verwendete Zertifikatsverwaltung unter /opt/lamp/certificates sowie das Skript create-certificate.sh setzen voraus, dass der Beitrag LAMP Stack für Laravel auf WSL installieren bereits umgesetzt wurde.

Docker Engine in WSL installieren

Docker Engine lässt sich direkt in einer Linux-Distribution innerhalb von WSL installieren. Für ein schnelles lokales Setup können wir den Convenience-Installer verwenden.

curl -fsSL https://get.docker.com | sh

Dieser Weg ist bequem, aber nicht die Standardempfehlung für Umgebungen, in denen wir jeden Installationsschritt strikt dokumentieren wollen. Für eine lokale Entwicklungsmaschine ist er oft ausreichend.

Danach fügen wir unseren Benutzer zur Docker-Gruppe hinzu:

sudo usermod -aG docker $USER

Anschließend müssen wir die Login-Session neu starten, damit die Gruppenmitgliedschaft aktiv wird.

Ob Docker danach erreichbar ist, prüfen wir einfach mit:

docker ps

Wenn der Befehl ohne sudo funktioniert, ist die Basis fertig.

Mailpit als dauerhaften Container starten

Jetzt starten wir Mailpit als einzelnen Container, der dauerhaft im Hintergrund läuft:

docker run -d --name mailpit --restart unless-stopped \\
  -p 1025:1025 \\
  -p 8025:8025 \\
  axllent/mailpit

Dabei werden zwei Ports nach außen veröffentlicht:

• 1025 für SMTP
• 8025 für Weboberfläche und API

Für lokale Entwicklung ist das genau der gewünschte Zuschnitt. Mailpit akzeptiert auf Port 1025 standardmäßig unverschlüsseltes SMTP ohne Authentifizierung.

Den ersten Test machen wir direkt im Browser unter:

http://localhost:8025

WSL-Dienste sind von Windows aus typischerweise über localhost erreichbar. Deshalb können wir die Weboberfläche meist direkt im Windows-Browser öffnen, obwohl der Container in WSL läuft.

Ob der Container läuft, sehen wir mit:

docker ps

Wenn Mailpit Probleme macht, hilft oft schon ein Blick in die Logs:

docker logs mailpit

Projekte mit Mailpit verbinden

Sobald der Container läuft, können lokale Anwendungen ihre Mails an Mailpit senden. Für viele nicht-containerisierte Projekte in WSL oder lokal ausgeführte Anwendungen funktioniert 127.0.0.1 mit Port 1025 direkt.

Ein typisches Laravel-Beispiel sieht so aus:

MAIL_MAILER=smtp
MAIL_HOST=127.0.0.1
MAIL_PORT=1025
MAIL_USERNAME=null
MAIL_PASSWORD=null

Damit landen ausgehende Test-Mails in der Mailpit-Oberfläche statt bei echten Empfängern.

Wenn ein Projekt selbst in Containern läuft, müssen wir den SMTP-Host gesondert prüfen. Innerhalb eines Containers zeigt 127.0.0.1 auf den Container selbst, nicht auf den WSL-Host. In solchen Setups hängt die richtige Adresse vom verwendeten Netzwerkmodus ab. Der Artikel hier konzentriert sich auf die zentrale WSL-Instanz als lokales Ziel für Projekte, die diesen Host erreichen können.

Wenn alles funktioniert hat sollten die Mails korrekt von Mailpit abgefangen werden und die Oberfläche so aussehen:

Optional: Mailpit unter mailpit.test per Apache bereitstellen

http://localhost:8025 reicht funktional völlig aus. Eine eigene Domain wie https://mailpit.test ist nur eine Komfortschicht. Sie kann trotzdem sinnvoll sein, wenn wir Mailpit ähnlich wie andere lokale Projekte über einen festen Hostnamen aufrufen möchten.

Bevor wir einen VHost anlegen, aktivieren wir die nötigen Apache-Module. Für das Reverse-Proxy-Setup brauchen wir mindestens proxy und proxy_http. Wenn der Zugriff per HTTPS erfolgen soll, kommt ssl dazu:

sudo a2enmod ssl proxy proxy_http
sudo service apache2 reload

Falls in der WSL-Distribution systemd aktiviert ist, können wir statt service auch systemctl reload apache2 verwenden. Für eine allgemein funktionierende Anleitung bleibt service die neutralere Wahl.

Danach legen wir den VHost an:

sudo tee /etc/apache2/sites-available/mailpit.conf > /dev/null <<'EOF'
<VirtualHost *:80>
    ServerAdmin admin@admin-code.de
    ServerName mailpit.test

    Redirect permanent / https://mailpit.test/
</VirtualHost>

<VirtualHost *:443>
    ServerName mailpit.test
    ServerAdmin admin@admin-code.de

    ErrorLog /var/log/apache2/mailpit-error.log
    CustomLog /var/log/apache2/mailpit-access.log combined

    SSLEngine on
    SSLCertificateFile /etc/ssl/certs/mailpit.test.crt
    SSLCertificateKeyFile /etc/ssl/private/mailpit.test.key

    ProxyPreserveHost On
    ProxyPass / http://127.0.0.1:8025/
    ProxyPassReverse / http://127.0.0.1:8025/
</VirtualHost>
EOF

Anschließend aktivieren wir die Site und laden Apache neu:

sudo a2enmod proxy proxy_http
sudo a2ensite mailpit.conf
sudo service apache2 reload

Apache nimmt damit Anfragen an mailpit.test entgegen und leitet sie intern an Mailpit auf 127.0.0.1:8025 weiter.

Optional: Zertifikat und Hosts-Eintrag

Dieser Teil ist stark vom lokalen Setup abhängig. Wenn bereits ein vorhandenes Zertifikats-Setup im Einsatz ist, können wir ein Zertifikat für mailpit.test darüber erzeugen. In WSL-Setups, die auf unserem vorhandenen LAMP-Aufbau basieren, liegt die Zertifikatsverwaltung unter /opt/lamp/certificates.

Dann könnte der Ablauf so aussehen:

cd /opt/lamp/certificates
sudo ./create-certificate.sh mailpit.test

Dadurch sollten folgende Dateien entstehen:

mailpit.test.crt
mailpit.test.key

Apache erwartet Zertifikate und private Schlüssel normalerweise in den entsprechenden Systemverzeichnissen.

Das Zertifikat wird nach /etc/ssl/certs/ verschoben:

sudo mv /opt/lamp/certificates/mailpit.test.crt /etc/ssl/certs/

Der private Schlüssel wird nach /etc/ssl/private/ verschoben:

sudo mv /opt/lamp/certificates/mailpit.test.key /etc/ssl/private/

Damit Windows weiß, dass mailpit.test auf den lokalen Rechner zeigen soll, muss die Domain in die Windows-Hosts-Datei eingetragen werden. Mit installiertem gsudo kann dies direkt aus WSL heraus durchgeführt werden:

"/mnt/c/Program Files/gsudo/Current/gsudo.exe" -d "echo ::1 mailpit.test >> %windir%\System32\drivers\etc\hosts"

Dadurch wird folgender Eintrag in der Windows-Hosts-Datei ergänzt:

::1 mailpit.test

Typische Fehlerquellen

Wenn http://localhost:8025 nicht erreichbar ist, prüfen wir zuerst, ob der Container wirklich läuft:

docker ps

Taucht mailpit dort nicht auf, helfen die Container-Logs:

docker logs mailpit

Wenn der Container läuft, aber Port 8025 oder 1025 schon belegt ist, startet Mailpit unter Umständen nicht korrekt. Dann müssen wir den Portkonflikt auflösen oder andere Host-Ports wählen.

Wenn mailpit.test zwar aufgelöst wird, Apache aber keine Inhalte weiterleitet, fehlen häufig die Proxy-Module. Dann aktivieren wir sie noch einmal explizit:

sudo a2enmod proxy proxy_http
sudo service apache2 reload

Bei HTTPS kommt zusätzlich ssl dazu, falls das Modul noch nicht geladen ist.

Falls docker nur mit sudo funktioniert, wurde die neue Gruppenmitgliedschaft meist noch nicht übernommen. Dann hilft eine neue Login-Session in WSL.

Wenn der Aufruf aus dem Windows-Browser nicht funktioniert, obwohl der Dienst in WSL läuft, testen wir zuerst http://localhost:8025. Diese Variante ist technisch einfacher als die zusätzliche Domain mit Reverse Proxy und hilft dabei, den Fehler auf Netzwerk, Apache oder Hosts-Datei einzugrenzen.

Für lokale Entwicklung ist dieses Setup angenehm schlank: ein Container, feste SMTP-Daten und eine Oberfläche, die wir bei Bedarf auch unter eigener Domain bereitstellen können. Wenn wir ähnliche WSL-Setups betreiben, finden Sie im Blog von ADMIN CODE weitere Anleitungen für lokale Entwicklungsumgebungen. Wenn bei unserem Setup Docker, Apache oder die Einbindung in bestehende Projekt-Stacks hakt, melden Sie sich direkt über https://www.admin-intelligence.de/kontakt/.