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 möchten, das Backend später auszutauschen, oder eine sicherere Möglichkeit benötigen, 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 anfängt, praktisch zu wirken.

HAProxy passt gut in diese Rolle. Stellen Sie sich es als den Traffic-Manager vor, der vor Ihrer Anwendung sitzt: Anfragen treffen zunächst 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 saubere Grenze zwischen dem Internet und dem Service, den Sie tatsächlich ausführen.

Dieses Handbuch strukturiert die erste Bereitstellung absichtlich: 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 Reibung beginnt, 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 freizulegen 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.

Quick HAProxy Terms That Make the Rest of This Guide Easier

You only need a small vocabulary set to follow a first HAProxy deployment confidently. The table below covers the terms that matter in this guide.

For this guide, reverse proxy is the first mental model to keep in mind. HAProxy sits in front of something else and controls the handoff. Load balancing is the extended capability that becomes useful when you add multiple backend servers later.

The two terms that matter most once you open the config are frontend and backend. The frontend is where the client arrives. The backend is where HAProxy sends the request next. A health check matters because it lets HAProxy notice when a target should stop receiving traffic.

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 weitergeleitet 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 es Ihnen eine kontrollierte öffentliche Schnittstelle vor der Anwendung gibt.

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 alle 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 diesem Leitfaden sieht wie folgt 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 – ist das eine saubere Lösung, da das Layout leicht zu überprüfen bleibt.

💡 Tipp: Dieser Leitfaden 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
• Eingehend HTTP erlaubt, wenn Sie UFW oder Firewall-Regeln auf Provider-Seite verwenden

Überprüfen Sie zunächst 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 in die Docker-Installation abzuweichen.

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 aus der ss-Überprüfung bedeutet normalerweise, dass Port 80 frei ist. Wenn Sie nginx, apache2, caddy oder einen anderen Service sehen, der bereits dort lauscht, 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 mit der Erstellung eines kleinen Projektordners für die zwei Dateien, 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 exakten 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 bereitgestellt 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 bietet 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 bindet.

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-Integrität überprüft wird. Erstellen Sie als Nächstes haproxy.cfg:

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 bereitstellen kann, und mode http in defaults hält das gesamte Beispiel im HTTP-Modus, sodass das Listener- und Backend-Verhalten konsistent und lesbar bleibt.

✏️ HINWEIS: Ein Detail ist vor der Abschnittaufschlüsselung erwähnenswert: balance roundrobin wird explizit gesetzt, da neuere HAProxy-Versionen den Standard-Backend-Algorithmus zu random geändert haben, und roundrobin ist beim ersten Durchgang leichter vorhersehbar 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 beabsichtigt. Die Beibehaltung der ursprünglichen Client-IP ist später nützlich, aber diese erste Bereitstellung geht um die Bewährung von Routing und Backend-Integrität, nicht um das Unterrichten von Header-Verhalten mit einem Demo-Container, 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 reconciliert den vollständigen Two-Service-Stack:

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 wrappen diesen Text in eine kleine HTML-Response, konzentrieren Sie sich also mehr auf die Body-Phrase als auf die exakte Formatierung.

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

Überprüfen Sie für eine zweite Validierungsoberflä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 Permission denied 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 im Container.

  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 im Container.

---

• 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 in Konflikt stehenden Service.

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

---

• Syntax-Überprüfung meldet unknown keyword 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 gemeldet wird.

  Warum das passiert: HAProxy’s 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 demo-Servicenamen erneut.

  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 Beweise 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 zuerst diese eine Sache korrigieren.

Wohin nach der Installation

Sobald die Single-Backend-Demo 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 Config validieren Sie zuerst und laden HAProxy dann 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 diesem Leitfaden 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 Operations-Projekt 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.