Wie man HAProxy mit Docker Compose auf Ubuntu VPS installiert

Ein Web-Service auf einem VPS ist einfach direkt freizugeben — bis Sie eine saubere öffentliche Schnittstelle wünschen, die Freiheit haben, das Backend später auszutauschen, oder eine sicherere Möglichkeit, den Datenverkehr zu etwas Defektem zu stoppen. Das ist der Punkt, an dem ein Proxy aufhört, sich wie „etwas für große Infrastruktur-Teams” anzufühlen, und praktisch wird.

HAProxy passt gut in diese Rolle. Stellen Sie sich es als den Traffic-Manager vor, der vor Ihrer Anwendung sitzt: Anfragen treffen zuerst auf HAProxy, und HAProxy entscheidet, wohin sie als nächstes gehen sollen. Sie benötigen keinen großen Cluster, um davon zu profitieren. Selbst auf einem Ubuntu 24.04 VPS bietet es Ihnen eine sauberere Grenze zwischen dem Internet und dem Service, den Sie tatsächlich ausführen.

Dieses Handbuch hält die erste Bereitstellung absichtlich strukturiert: ein Ubuntu 24.04 VPS, Docker Compose, ein HAProxy-Container, ein Demo-Backend und der Beweis, dass Routing wirklich funktioniert.

Warum HAProxy wichtig ist, bevor Sie es brauchen

Stellen Sie sich einen kleinen VPS vor, auf dem heute eine App einwandfrei läuft. Sie antwortet auf einem Port, die Website lädt und alles sieht gut aus. Die Probleme beginnen, wenn Sie einen stabilen öffentlichen Einstiegspunkt möchten, die Möglichkeit, das Backend später zu ersetzen, ohne die öffentliche Adresse zu ändern, oder eine vordere Schicht, die den Datenverkehr zu einem fehlerhaften Service stoppen kann. Die App direkt freizugeben beginnt überraschend schnell fragil zu wirken.

Diese Anforderungen deuten alle auf die gleiche fehlende Schicht hin: einen kontrollierten Einstiegspunkt zwischen dem Internet und Ihrer Anwendung. HAProxy bietet diese Schicht. Clients verbinden sich zuerst mit HAProxy, und HAProxy entscheidet, wohin jede Anfrage als nächstes geht.

Diese Trennung ist nützlich, auch bevor Sie mehrere Server haben. Sie gibt Ihnen jetzt einen saubereren öffentlichen Edge und einen sichereren Weg zu späteren Änderungen wie Backend-Austausch, Health-aware Routing und HTTPS. Der Rest des Leitfadens zeigt dieses Muster in seiner einfachsten funktionierenden Form und überprüft es mit einem echten Request-Pfad.

Schnelle HAProxy-Begriffe, die den Rest dieses Leitfadens erleichtern

Sie benötigen nur einen kleinen Wortschatz, um eine erste HAProxy-Bereitstellung sicher durchzuführen. Die folgende Tabelle behandelt die Begriffe, die in diesem Leitfaden wichtig sind.

Für diesen Leitfaden ist Reverse Proxy das erste mentale Modell, das Sie im Hinterkopf behalten sollten. HAProxy sitzt vor etwas anderem und kontrolliert die Übergabe. Load Balancing ist die erweiterte Funktion, die nützlich wird, wenn Sie später mehrere Backend-Server hinzufügen.

Die beiden Begriffe, die am wichtigsten sind, sobald Sie die Konfiguration öffnen, sind Frontend und Backend. Das Frontend ist der Ort, an dem der Client ankommt. Das Backend ist der Ort, an den HAProxy die Anfrage als Nächstes sendet. Ein Health Check ist wichtig, da er HAProxy ermöglicht, festzustellen, wenn ein Ziel keinen Traffic mehr erhalten sollte.

Wofür HAProxy gut ist — und was dieser Leitfaden absichtlich überspringt

Wenn Sie sich Ihren Stack als Bürogebäude vorstellen, ist HAProxy die Rezeption: Der Datenverkehr kommt dort zuerst an, wird in den richtigen Raum geleitet und wird nicht mehr an einen Raum gesendet, der eindeutig nicht verfügbar ist.

In diesem Leitfaden bedeutet das drei anfängertaugliche Aufgaben:

1. eingehende HTTP-Anfragen akzeptieren
2. sie an das Demo-Backend weiterleiten
3. überwachen, ob dieses Backend gesund genug ist, um weiterhin Datenverkehr zu erhalten

Das ist bereits mit einem Backend nützlich, da Sie eine kontrollierte öffentliche Schnittstelle vor der Anwendung haben.

Später skaliert das gleiche Muster sauber. Sie können das Backend ersetzen, weitere Backends hinzufügen, HTTPS einführen oder HAProxy den Datenverkehr auf mehrere Ziele verteilen lassen, anstatt nur auf eines. Um den ersten Durchgang lehrbar zu halten, bleibt dieser Leitfaden im HTTP-Modus und überspringt absichtlich TLS-Terminierung, ACLs, Rate Limiting, Stick Tables und HA-Paare. Das sind alles echte HAProxy-Themen. Sie sind nur nicht der richtige Ausgangspunkt für eine erste funktionierende Bereitstellung.

Was Sie bauen und was Sie zuerst brauchen

Bevor Sie Dateien erstellen, ist es hilfreich, die endgültige Form des Stacks zu sehen. Die Bereitstellung in dieser Anleitung sieht folgendermaßen aus:

Client browser or curl
        |
        v
HAProxy frontend (:80)
        |
        v
demo backend service (demo:5678)

Optional local-only validation:
HAProxy stats frontend (127.0.0.1:8404/stats)

Docker Compose ist hier der Hauptweg, da es die erste Installation reproduzierbar, sichtbar und leicht zu bearbeiten hält. Anstatt am ersten Tag ein benutzerdefiniertes Image zu erstellen, behalten Sie die HAProxy-Konfiguration auf dem Host, mounten sie in den Container und starten den gesamten Stack aus einer Datei. Auf einer selbstverwalteten Ubuntu VPS – zum Beispiel einer AlexHost VPS – passt das perfekt, da das Layout leicht zu überprüfen bleibt.

💡 Tipp: Diese Anleitung verwendet Docker Compose plus ein bind-gemountetes haproxy.cfg absichtlich. Es ist der transparenteste Weg für die erste Installation, da Sie die Proxy-Konfiguration direkt bearbeiten können, ohne einen Image-Build-Schritt hinzuzufügen.

Bevor Sie beginnen, stellen Sie sicher, dass diese Grundlagen vorhanden sind:

• Ubuntu 24.04 VPS
• Docker Engine installiert
• Docker Compose v2 verfügbar über docker compose
• Terminalzugriff und Berechtigung zum Ausführen von Docker
• Port 80 verfügbar auf dem Host
• Eingehender HTTP erlaubt, wenn Sie UFW oder Firewall-Regeln auf Provider-Seite verwenden

Überprüfen Sie zuerst Ihre Ubuntu-Version

lsb_release -a

Bestätigen Sie anschließend, dass Docker und modernes Compose verfügbar sind:

docker --version
docker compose version

Wenn beide Befehle Versionsinformationen zurückgeben, ist die Container-Runtime-Seite bereit und Sie können sich auf HAProxy konzentrieren, anstatt einen Umweg zur Docker-Installation zu machen.

Stellen Sie anschließend sicher, dass Port 80 nicht bereits verwendet wird, und überprüfen Sie dann, ob UFW aktiv ist und ob HTTP bereits erlaubt ist:

sudo ss -tlnp | grep -E ':(80)s' || true
sudo ufw status
sudo ufw allow 80/tcp

✏️ HINWEIS: Keine Ausgabe der ss-Überprüfung bedeutet normalerweise, dass Port 80 frei ist. Wenn Sie nginx, apache2, caddy oder einen anderen Service sehen, der bereits dort abhört, beheben Sie das zuerst. Es ist ein zehn Sekunden langer Preflight-Schritt, der später viel Verwirrung spart.

Im obigen Beispiel zeigt sudo ufw status Status: active, und 80/tcp ist bereits in der Zulassungsliste vorhanden. Deshalb gibt sudo ufw allow 80/tcp Skipping adding existing rule zurück, anstatt eine neue hinzuzufügen. Diese Ausgabe ist normal und bedeutet einfach, dass die Firewall-Regel bereits vorhanden war.

Erstellen Sie den Projektordner und die Compose-Datei

Beginnen Sie damit, einen kleinen Projektordner für die zwei Dateien zu erstellen, die diese erste Bereitstellung benötigt:

mkdir -p ~/haproxy-docker
cd ~/haproxy-docker

Danach sollte das Layout so klein wie möglich sein:

~/haproxy-docker/
├── compose.yaml
└── haproxy.cfg

Erstellen Sie nun compose.yaml und verwenden Sie diesen genauen Inhalt:

services:
  demo:
    image: hashicorp/http-echo:1.0
    command: ["-listen=:5678", "-text=Hello from the HAProxy demo backend"]
    restart: unless-stopped

  haproxy:
    image: haproxy:3.4.1
    depends_on:
      - demo
    ports:
      - "80:80"
      - "127.0.0.1:8404:8404"
    volumes:
      - ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro
    sysctls:
      net.ipv4.ip_unprivileged_port_start: "0"
    restart: unless-stopped

Diese Datei verbindet die Container miteinander, definiert aber noch keine HAProxy-Anfraglogik. Sie teilt Docker mit, welche Images ausgeführt werden sollen, welche Ports veröffentlicht werden sollen und wo die HAProxy-Konfiguration vom Host aus eingebunden wird.

Die folgenden Einstellungen sind die wichtigsten für eine saubere erste Bereitstellung:

Ein weiteres Detail ist hier wichtig: Es gibt kein benutzerdefiniertes Docker-Netzwerk in dieser Datei, da Docker Compose automatisch ein Standardnetzwerk erstellt. Das gibt Ihnen Service-Namen-DNS innerhalb des Projekts, weshalb HAProxy das Backend als demo:5678 erreichen kann, ohne zusätzliche Verkabelung.

⚠️ Warnung: Port 80 ist ein privilegierter Port, daher ist die sysctls-Zeile nicht dekorativ. Das Ändern der Host-Zuordnung zu 8080:80 entfernt nicht die Anforderung für privilegierte Ports innerhalb des Containers, wenn HAProxy immer noch intern an :80 gebunden ist.

Schreiben und Validieren einer minimalen haproxy.cfg

Mit der Container-Verkabelung vorhanden, benötigt HAProxy immer noch Anweisungen, wo der Datenverkehr ankommt, wohin er gehen soll und wie die Backend-Gesundheit überprüft wird. Erstellen Sie haproxy.cfg als nächstes:

global
    log stdout format raw local0

defaults
    mode http
    timeout connect 5s
    timeout client 30s
    timeout server 30s

frontend http
    bind :80
    default_backend demo_backend

backend demo_backend
    balance roundrobin
    server demo1 demo:5678 check

frontend stats
    bind :8404
    stats enable
    stats refresh 10s
    stats uri /stats

Dies ist eine minimale Konfiguration, aber keine wegwerfbare. log stdout format raw local0 ist die Container-freundliche Logging-Wahl, da Docker stdout leicht anzeigen kann, und mode http in defaults hält das gesamte Beispiel im HTTP-Modus, sodass das Listener- und Backend-Verhalten konsistent und lesbar bleiben.

✏️ HINWEIS: Ein Detail ist vor der Abschnittaufschlüsselung erwähnenswert: balance roundrobin ist explizit gesetzt, da neuere HAProxy-Versionen den Standard-Backend-Algorithmus zu random geändert haben, und roundrobin ist leichter vorhersehbar beim ersten Durchgang zu unterrichten.

Hier ist die Aufschlüsselung in einfachem Englisch für jeden Abschnitt:

Sie könnten eine Sache vermissen: option forwardfor. Diese Auslassung ist im Basispfad absichtlich. Die Beibehaltung der ursprünglichen Client-IP ist später nützlich, aber diese erste Bereitstellung geht darum, Routing und Backend-Gesundheit zu beweisen, nicht Header-Verhalten mit einem Demo-Container zu unterrichten, der dieses Signal nicht besonders wertvoll macht.

💡 Tipp: Validieren Sie immer die HAProxy-Konfiguration, bevor Sie den vollständigen Stack starten. Da diese Konfiguration auf das Backend nach seinem Compose-Servicenamen (demo) verweist, starten Sie dieses Backend zuerst, damit HAProxy es während der Validierung auflösen kann.

Führen Sie die Validierung aus demselben Projektverzeichnis aus:

docker compose up -d demo
docker compose run --rm --no-deps haproxy haproxy -V -c -f /usr/local/etc/haproxy/haproxy.cfg

Wenn der zweite Befehl mit Configuration file is valid endet, haben Sie bereits bewiesen, dass HAProxy die Datei korrekt analysieren und das Backend-Ziel auflösen kann, bevor ein Live-Listener startet.

Stack starten und Proxy-Funktion nachweisen

Nachdem die Konfiguration validiert wurde, starten Sie den Stack im Detached-Modus:

Da der Validierungsschritt bereits demo gestartet hat, bringt dieser Befehl hauptsächlich HAProxy hoch und gleicht den vollständigen Two-Service-Stack ab:

docker compose up -d

Überprüfen Sie dann, ob beide Container aktiv sind:

docker compose ps

Diese Prozessansicht ist nur der erste Kontrollpunkt. Sie bestätigt, dass Docker die Container gestartet hat, aber noch nicht, dass HAProxy erfolgreich Traffic zum Backend leitet. Die nächste Anfrage überprüft den tatsächlichen Datenpfad.

Führen Sie nun den eigentlichen Routing-Test vom VPS selbst aus:

curl -i http://127.0.0.1

Das Erfolgssignal ist HTTP/1.1 200 OK plus der Response-Body mit Hello from the HAProxy demo backend. Einige http-echo-Builds umhüllen diesen Text in eine kleine HTML-Response, konzentrieren Sie sich also mehr auf die Body-Phrase als auf die genaue Formatierung.

Wenn Sie einen Browser-Level-Nachweis möchten, öffnen Sie http://YOUR_SERVER_IP von einem anderen Computer aus.

Überprüfen Sie für eine zweite Validierungsfläche die lokale Stats-Seite vom VPS:

curl http://127.0.0.1:8404/stats

Auf der Stats-Seite sind die nützlichsten Signale ein Frontend namens http, ein Backend namens demo_backend, eine Server-Zeile namens demo1, Status angezeigt als UP, und normalerweise ein Last-Check-Wert wie L4OK in 0ms. Beachten Sie auch eine kleine Docker-Besonderheit: Kurzsyntax depends_on steuert die Startreihenfolge, wartet aber nicht darauf, dass ein Service gesund wird. Wenn der allererste curl direkt nach dem Start einmal fehlschlägt, warten Sie ein paar Sekunden und versuchen Sie es erneut, bevor Sie davon ausgehen, dass die Konfiguration falsch ist.

Der Unterschied zwischen Prozesszustand und echtem Erfolg lässt sich leichter in Tabellenform darstellen:

Häufige Fehler beim ersten Start und schnelle Lösungen

Wenn das Setup nicht sofort funktioniert, widerstehen Sie dem Drang, beide Dateien auf einmal umzuschreiben. Die meisten Fehler beim ersten Start auf diesem Stack sind vorhersehbar und werden viel einfacher zu beheben, wenn Sie jeweils eine Variable ändern.

Verwenden Sie diese Matrix als schnelle Diagnose-Ebene:

• HAProxy wird sofort beendet

  Wahrscheinliche Ursache: haproxy.cfg fehlt.

  Schnelle Lösung: Stellen Sie sicher, dass haproxy.cfg neben compose.yaml vorhanden ist.

  Warum das passiert: Das offizielle Image wird nicht mit einer einsatzbereiten Konfiguration ausgeliefert.

---

• Fehler besagt, dass /usr/local/etc/haproxy/haproxy.cfg nicht geöffnet werden kann

  Wahrscheinliche Ursache: Falscher Bind-Mount-Pfad.

  Schnelle Lösung: Überprüfen Sie ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro genau.

  Warum das passiert: HAProxy kann ohne eine gültige Konfigurationsdatei nicht starten.

---

• Fehler besagt Berechtigung verweigert auf Port 80

  Wahrscheinliche Ursache: Problem beim Binding von privilegierten Ports.

  Schnelle Lösung: Behalten Sie net.ipv4.ip_unprivileged_port_start: “0” in Compose bei, oder verschieben Sie sowohl HAProxy als auch den veröffentlichten Port zu 8080.

  Warum das passiert: Der Container wird als Nicht-Root-Benutzer haproxy ausgeführt.

---

• Sie haben die Zuordnung zu 8080:80 geändert und erhalten immer noch einen Binding-Fehler

  Wahrscheinliche Ursache: HAProxy bindet immer noch an :80 innerhalb des Containers.

  Schnelle Lösung: Ändern Sie sowohl die Host-Zuordnung als auch die interne bind-Zeile, wenn Sie sich von Port 80 entfernen.

  Warum das passiert: Die Regel für privilegierte Ports gilt auch innerhalb des Containers.

---

• Port 80 wird bereits verwendet

  Wahrscheinliche Ursache: Ein anderer Service nutzt den Host-Port.

  Schnelle Lösung: Führen Sie die ss-Überprüfung erneut aus und stoppen oder verschieben Sie den konfliktierenden Service.

  Warum das passiert: Nur ein Prozess kann auf demselben Host-Port lauschen.

---

• Syntax-Überprüfung meldet unbekanntes Schlüsselwort oder zeilenspezifische Fehler

  Wahrscheinliche Ursache: Tippfehler in der HAProxy-Konfiguration.

  Schnelle Lösung: Führen Sie die Syntax-Überprüfung erneut aus und beheben Sie die genaue Zeile, die sie meldet.

  Warum das passiert: Der HAProxy-Parser ist streng, was hilfreich ist, wenn Sie ihn absichtlich nutzen.

---

• Container sind aktiv, aber curl gibt keine Demo-Antwort zurück

  Wahrscheinliche Ursache: Routing-Pfad ist falsch.

  Schnelle Lösung: Überprüfen Sie default_backend demo_backend, server demo1 demo:5678 check und den Service-Namen demo.

  Warum das passiert: Ein laufender Container ist kein Beweis für einen korrekten Frontend-zu-Backend-Pfad.

---

• Lokales curl funktioniert, aber die Website ist von außen nicht erreichbar

  Wahrscheinliche Ursache: Firewall oder Provider-Sicherheitsregel.

  Schnelle Lösung: Öffnen Sie Port 80 in UFW und in jeder Provider-seitigen Firewall.

  Warum das passiert: Lokales Publishing kann funktionieren, auch wenn der öffentliche Zugriff noch blockiert ist.

⚠️ Warnung: Ändern Sie jeweils eine Sache. Wenn Sie blind sowohl compose.yaml als auch haproxy.cfg bearbeiten, wird es viel schwieriger zu erkennen, ob der Fehler ein Dateipfad-Problem, ein Port-Problem oder ein Routing-Problem ist.

Wenn Sie schnelle Hinweise benötigen, halten Sie diese Befehle in der Nähe:

docker compose logs haproxy
docker compose ps
docker compose up -d demo
docker compose run --rm --no-deps haproxy haproxy -V -c -f /usr/local/etc/haproxy/haproxy.cfg
sudo ss -tlnp | grep -E ':(80|8404)s' || true

Dies sind die drei Warnmuster, die am meisten wert sind, auf den ersten Blick erkannt zu werden:

[ALERT] ... Cannot open configuration file /usr/local/etc/haproxy/haproxy.cfg : No such file or directory
[ALERT] ... Starting frontend http: cannot bind socket (Permission denied) [0.0.0.0:80]
[ALERT] ... parsing [/usr/local/etc/haproxy/haproxy.cfg:12] : unknown keyword 'chekc'; did you mean 'check' maybe?

Das ist der beruhigende Teil einer kleinen ersten Bereitstellung: Die Fehlerformen sind normalerweise auch klein. Sie müssen nicht von vorne anfangen. Sie müssen nur identifizieren, welche Ebene sich beschwert, und diese eine Sache zuerst korrigieren.

Wohin nach der Installation

Sobald die Demo mit einem Backend funktioniert, ist die Architektur bereits nützlich. Der nächste echte Schritt besteht darin, den Demo-Container durch Ihre tatsächliche Anwendung zu ersetzen, während Sie die gleiche HAProxy-Struktur beibehalten. Danach fügen Sie HTTPS/TLS als separaten Folgenschritt hinzu und behandeln Domain-basiertes Routing sowie ACLs als separate Themen, anstatt sie in diese erste Installation zu drängen.

Wenn Sie bereit für mehr als ein Backend sind, wird das gleiche Muster deutlich sinnvoll:

backend app_backend
    balance roundrobin
    server app1 app1:8080 check
    server app2 app2:8080 check

Für sichere Änderungen an einer bind-mounted Konfiguration validieren Sie zuerst und laden dann HAProxy elegant neu:

docker compose up -d demo
docker compose run --rm --no-deps haproxy haproxy -V -c -f /usr/local/etc/haproxy/haproxy.cfg
docker compose kill -s HUP haproxy

📝 Hinweis: Die Stats-Seite ist in dieser Anleitung absichtlich nur lokal verfügbar. Falls Sie sie jemals öffentlich verfügbar machen, fügen Sie zuerst Authentifizierung und Zugriffskontrolle hinzu.

Das bringt Sie zurück zum ursprünglichen Problem: Sie wollten eine saubere Eingangstür vor einem Service, ohne das erste Setup in ein vollständiges Betriebsprojekt zu verwandeln. Sie haben jetzt diesen funktionierenden Weg. Noch wichtiger ist, dass Sie auch das richtige mentale Modell haben: HAProxy empfängt den Traffic zuerst, leitet ihn dorthin weiter, wo er hingehört, und gibt Ihnen eine sauberere Möglichkeit, den Stack auf einem selbstverwalteten VPS zu erweitern, ohne die Kontrolle über die Konfiguration zu verlieren.