Cum să instalezi HAProxy cu Docker Compose pe Ubuntu VPS

One web service on a VPS is easy to expose directly — until you want one clean public front door, the freedom to swap the backend later, or a safer way to stop sending traffic to something broken. That is the point where a proxy stops feeling like “something for big infrastructure teams” and starts feeling practical.

HAProxy fits that role well. Think of it as the traffic manager sitting in front of your application: requests hit HAProxy first, and HAProxy decides where they should go next. You do not need a large cluster to benefit from that. Even on one Ubuntu 24.04 VPS, it gives you a cleaner edge between the internet and the service you are actually running.

This guide keeps the first deployment intentionally structured: one Ubuntu 24.04 VPS, Docker Compose, one HAProxy container, one demo backend, and proof that routing really works.

De ce Contează HAProxy Înainte să Ai Nevoie de El

Imaginează-ți un mic VPS care rulează o aplicație perfect astazi. Răspunde pe un port, site-ul se încarcă, și totul arată bine. Fricțiunea apare când vrei un punct de intrare public stabil, opțiunea de a înlocui backend-ul mai târziu fără a schimba adresa publică, sau un strat frontal care poate opri trimiterea de trafic către un serviciu care nu funcționează. Expunerea directă a aplicației începe să se simtă fragil surprinzător de repede.

Aceste cerințe indică toate către același strat lipsă: un punct de intrare controlat între internet și aplicația ta. HAProxy furnizează acel strat. Clienții se conectează mai întâi la HAProxy, iar HAProxy decide unde merge fiecare cerere în continuare.

Acea separare este utilă chiar și înainte să ai mai multe servere. Îți oferă o margine publică mai curată acum și o cale mai sigură pentru schimbări ulterioare, cum ar fi înlocuirea backend-ului, rutarea conștientă de sănătate, și HTTPS. Restul ghidului arată acel model în forma sa cea mai simplă care funcționează și îl verifică cu o cale de cerere reală.

Termeni HAProxy rapizi care fac restul acestui ghid mai ușor

Trebuie doar un set mic de vocabular pentru a urma cu încredere o primă implementare HAProxy. Tabelul de mai jos acoperă termenii care contează în acest ghid.

Pentru acest ghid, reverse proxy este primul model mental pe care trebuie să-l ții în minte. HAProxy se află în fața a ceva altceva și controlează transmiterea. Load balancing este capacitatea extinsă care devine utilă atunci când adaugi mai târziu mai multe servere backend.

Cei doi termeni care contează cel mai mult odată ce deschizi configurația sunt frontend și backend. Frontend-ul este locul unde clientul sosește. Backend-ul este locul unde HAProxy trimite cererea în continuare. Un health check contează pentru că permite HAProxy să observe când o țintă ar trebui să înceteze să primească trafic.

Ce face bine HAProxy — și ce omite intenționat acest ghid

Dacă vă imaginați stiva dvs. ca o clădire de birouri, HAProxy este recepția: traficul ajunge acolo mai întâi, este direcționat în camera potrivită și încetează să fie trimis într-o cameră care este clar indisponibilă.

În acest ghid, aceasta se traduce în trei sarcini relevante pentru începători:

1. acceptă cererile HTTP primite
2. le transmite backend-ului demo
3. monitorizează dacă acel backend este suficient de sănătos pentru a continua să primească trafic

Aceasta este deja utilă cu un backend pentru că vă oferă o margine publică controlată în fața aplicației.

Mai târziu, același model se scalează curat. Puteți înlocui backend-ul, adăuga mai multe backend-uri, introduce HTTPS, sau lăsa HAProxy să distribuie traficul pe mai multe ținte în loc de doar una. Pentru a menține prima trecere ușor de învățat, acest ghid rămâne în modul HTTP și omite intenționat terminarea TLS, ACL-uri, limitarea ratei, tabele stick și perechi HA. Toate acestea sunt subiecte reale HAProxy. Pur și simplu nu sunt punctul de plecare potrivit pentru o primă implementare funcțională.

Ce construiești și ce ai nevoie mai întâi

Înainte de a crea fișiere, ajută să vezi forma finală a stack-ului. Implementarea din acest ghid arată așa:

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 este calea principală aici pentru că menține prima instalare reproductibilă, vizibilă și ușor de editat. În loc să construiești o imagine personalizată în prima zi, păstrezi configurația HAProxy pe gazdă, o montezi în container și pornești întregul stack dintr-un singur fișier. Pe un VPS Ubuntu auto-gestionat — de exemplu, un VPS AlexHost — aceasta se potrivește bine pentru că aspectul rămâne ușor de inspectat.

💡 Sfat: Acest ghid folosește Docker Compose plus un haproxy.cfg bind-mounted cu scop. Este cea mai transparentă cale de prima instalare pentru că poți edita configurația proxy direct fără a adăuga un pas de construire a imaginii.

Înainte de a începe, asigură-te că ai aceste elemente de bază în loc:

• Ubuntu 24.04 VPS
• Docker Engine instalat
• Docker Compose v2 disponibil prin docker compose
• Acces la terminal și permisiune de a rula Docker
• Portul 80 disponibil pe gazdă
• HTTP inbound permis dacă folosești UFW sau reguli de firewall pe partea furnizorului

Mai întâi, verifică versiunea Ubuntu

lsb_release -a

Apoi, confirmă că Docker și Compose modern sunt disponibili:

docker --version
docker compose version

Dacă ambele comenzi returnează informații despre versiune, partea runtime a containerului este gată și poți rămâne concentrat pe HAProxy în loc să faci o detură în instalarea Docker.

Apoi, asigură-te că portul 80 nu este deja în uz, apoi verifică dacă UFW este activ și dacă HTTP este deja permis:

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

✏️ NOTĂ: Nicio ieșire din verificarea ss de obicei înseamnă că portul 80 este liber. Dacă vezi nginx, apache2, caddy sau alt serviciu deja ascultând acolo, remediază asta mai întâi. Este un pas de preflight de zece secunde care economisește multă confuzie mai târziu.

În exemplul de mai sus, sudo ufw status arată Status: active, și 80/tcp este deja prezent în lista de permisiuni. De aceea sudo ufw allow 80/tcp returnează Skipping adding existing rule în loc să adauge una nouă. Această ieșire este normală și pur și simplu înseamnă că regula firewall-ului era deja în loc.

Creați Folderul Proiectului și Fișierul Compose

Începeți prin crearea unui mic folder de proiect pentru cele două fișiere necesare acestei prime implementări:

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

După aceea, aspectul ar trebui să fie cât mai mic posibil:

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

Acum creați compose.yaml și utilizați exact acest conținut:

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

Acest fișier conectează containerele între ele, dar nu definește încă logica cererilor HAProxy. El spune Docker-ului care imagini să ruleze, care porturi să publice și de unde va fi montată configurația HAProxy de pe gazdă.

Următoarele setări sunt cele care contează cel mai mult pentru o implementare curată și de început:

Un detaliu mai important conteaza aici: nu există o rețea Docker personalizată în acest fișier deoarece Docker Compose creează o rețea implicită automat. Aceasta vă oferă DNS cu nume de serviciu în cadrul proiectului, motiv pentru care HAProxy va putea atinge backend-ul ca demo:5678 fără cablare suplimentară.

⚠️ Avertisment: Portul 80 este un port privilegiat, deci linia sysctls nu este decorativă. Schimbarea mapării gazdei la 8080:80 nu elimină cerința portului privilegiat în interiorul containerului dacă HAProxy se leagă în continuare la :80 intern.

Scrieți și validați un minimal haproxy.cfg

Cu cablajul containerului în loc, HAProxy are nevoie încă de instrucțiuni pentru locul unde sosește traficul, unde ar trebui să meargă și cum este verificată sănătatea backend-ului. Creați haproxy.cfg în continuare:

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

Aceasta este o configurație minimală, dar nu este una de unică folosință. log stdout format raw local0 este alegerea de logging prietenoasă cu containerul, deoarece Docker poate expune stdout cu ușurință, iar mode http în defaults ține întregul exemplu în modul HTTP, astfel încât comportamentul listener-ului și backend-ului rămân consecvenți și lizibili.

✏️ NOTĂ: Un detaliu merită să fie evidențiat înainte de descompunerea secțiunilor: balance roundrobin este setat în mod explicit, deoarece versiunile mai noi ale HAProxy au schimbat algoritmul implicit al backend-ului la random, iar roundrobin este mai ușor de predat în mod previzibil la prima trecere.

Iată descompunerea în limba engleză simplă a fiecărei secțiuni:

Puteți observa un lucru lipsă: option forwardfor. Această omisiune este intenționată în calea de bază. Păstrarea IP-ului original al clientului este utilă mai târziu, dar această primă implementare este despre dovedirea rutării și sănătății backend-ului, nu despre predarea comportamentului header-ului cu un container demo care nu face acel semnal deosebit de valoros.

💡 Sfat: Validați întotdeauna configurația HAProxy înainte de a porni stiva completă. Deoarece această configurație se referă la backend-ul după numele serviciului Compose (demo), porniți mai întâi acel backend, astfel încât HAProxy să îl poată rezolva în timpul validării.

Rulați validarea din același director de proiect:

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

Dacă a doua comandă se termină cu Configuration file is valid, ați dovedit deja că HAProxy poate analiza fișierul corect și rezolva ținta backend-ului înainte ca orice listener live să pornească.

Porniți Stack-ul și Dovediți că Proxy-ul Funcționează

Odată ce configurația este validată, porniți stack-ul în modul detașat:

Deoarece pasul de validare a deja pornit demo, această comandă aduce în principal HAProxy și reconciliază stack-ul complet cu două servicii:

docker compose up -d

Apoi verificați dacă ambele containere sunt active:

docker compose ps

Acea vizualizare a proceselor este doar primul punct de control. Confirmă că Docker a pornit containerele, dar nu încă că HAProxy rutează cu succes traficul către backend. Următoarea cerere verifică calea de date reală.

Acum rulați testul de rutare efectiv din VPS-ul însuși:

curl -i http://127.0.0.1

Semnalul de succes este HTTP/1.1 200 OK plus corpul răspunsului care conține Hello from the HAProxy demo backend. Unele compilări http-echo înfășoară acel text într-un răspuns HTML mic, deci concentrați-vă pe fraza din corp mai mult decât pe formatarea exactă.

Dacă doriți o dovadă la nivel de browser, deschideți http://YOUR_SERVER_IP de pe o altă mașină.

Pentru o a doua suprafață de validare, verificați pagina de statistici doar pentru local din VPS:

curl http://127.0.0.1:8404/stats

Pe pagina de statistici, semnalele cele mai utile sunt un frontend numit http, un backend numit demo_backend, un rând de server numit demo1, stare afișată ca UP, și de obicei o valoare de ultimă verificare ca L4OK in 0ms. De asemenea, țineți minte o mică nuanță Docker: depends_on cu sintaxă scurtă controlează ordinea de pornire, dar nu așteaptă ca un serviciu să devină sănătos. Dacă prima curl eșuează o dată chiar după pornire, așteptați câteva secunde și încercați din nou înainte de a presupune că configurația este greșită.

Diferența dintre starea procesului și succesul real este mai ușor de ținut minte sub formă de tabel:

Greșeli comune la prima rulare și corecții rapide

Dacă configurarea nu funcționează imediat, rezistă tentației de a rescrie ambele fișiere deodată. Majoritatea eșecurilor la prima rulare pe acest stack sunt previzibile și devin mult mai ușor de reparat atunci când schimbi o variabilă la un moment dat.

Folosește această matrice ca strat de diagnostic rapid:

• HAProxy se închide imediat

  Cauza probabilă: haproxy.cfg lipsește.

  Corecție rapidă: Asigură-te că haproxy.cfg există lângă compose.yaml.

  De ce se întâmplă: Imaginea oficială nu vine cu o configurație gata de utilizare.

---

• Eroarea spune că nu poate deschide /usr/local/etc/haproxy/haproxy.cfg

  Cauza probabilă: Cale de bind-mount greșită.

  Corecție rapidă: Verifică ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro exact.

  De ce se întâmplă: HAProxy nu poate porni fără un fișier de configurație valid.

---

• Eroarea spune Permission denied pe portul 80

  Cauza probabilă: Problemă de legare a portului privilegiat.

  Corecție rapidă: Păstrează net.ipv4.ip_unprivileged_port_start: “0” în Compose, sau mută atât HAProxy cât și portul publicat la 8080.

  De ce se întâmplă: Containerul rulează ca utilizatorul non-root haproxy.

---

• Ai schimbat maparea la 8080:80 și încă primești o eroare de legare

  Cauza probabilă: HAProxy se leagă încă la :80 în interiorul containerului.

  Corecție rapidă: Schimbă atât maparea gazdei cât și linia internă bind dacă te îndepărtezi de portul 80.

  De ce se întâmplă: Regula portului privilegiat se aplică și în interiorul containerului.

---

• Portul 80 este deja în uz

  Cauza probabilă: Un alt serviciu deține portul gazdei.

  Corecție rapidă: Re-execută verificarea ss și oprește sau mută serviciul conflictual.

  De ce se întâmplă: Doar un proces poate asculta pe același port gazdei.

---

• Verificarea sintaxei raportează unknown keyword sau erori specifice liniei

  Cauza probabilă: Greșeală de tastare în configurația HAProxy.

  Corecție rapidă: Re-execută verificarea sintaxei și corectează linia exactă pe care o raportează.

  De ce se întâmplă: Parser-ul HAProxy este strict, ceea ce este util odată ce îl folosești intenționat.

---

• Containerele sunt active, dar curl nu returnează răspunsul demo

  Cauza probabilă: Calea de rutare este greșită.

  Corecție rapidă: Re-verifică default_backend demo_backend, server demo1 demo:5678 check și numele serviciului demo.

  De ce se întâmplă: Un container activ nu este dovada unei căi frontend-to-backend corecte.

---

• curl local funcționează dar site-ul este inaccesibil din exterior

  Cauza probabilă: Firewall sau regulă de securitate din partea furnizorului.

  Corecție rapidă: Deschide portul 80 în UFW și orice firewall din partea furnizorului.

  De ce se întâmplă: Publicarea locală poate funcționa chiar și atunci când accesul public este încă blocat.

⚠️ Avertisment: Schimbă un lucru la un moment dat. Dacă editezi atât compose.yaml cât și haproxy.cfg orb, faci mult mai greu să determini dacă eșecul este o problemă de cale de fișier, o problemă de port sau o problemă de rutare.

Atunci când ai nevoie de dovezi rapide, ține aceste comenzi la îndemână:

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

Acestea sunt cele trei modele de alertă care merită recunoscute la prima vedere:

[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?

Aceasta este partea liniștitoare a unei mici implementări inițiale: formele de eșec sunt de obicei și ele mici. Nu trebuie să începi din nou. Trebuie să identifici care strat se plânge și să corectezi mai întâi acel lucru.

Unde să Mergi După Instalare

Odată ce demo-ul cu un backend funcționează, arhitectura este deja utilă. Următorul pas real este să înlocuiești containerul demo cu aplicația ta reală, păstrând aceeași structură HAProxy. După aceea, adaugă HTTPS/TLS ca un pas de urmărire dedicat, și tratează rutarea bazată pe domeniu plus ACL-urile ca subiecte separate, mai degrabă decât să le grăbești în această primă instalare.

Când ești gata pentru mai mult de un backend, același model devine vizibil semnificativ:

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

Pentru editări sigure ale unei configurații montate cu bind, validează mai întâi și apoi reîncarcă HAProxy în mod elegant:

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

📝 Notă: Pagina de statistici este intenționat doar local în acest ghid. Dacă o expui vreodată public, adaugă mai întâi autentificarea și controalele de acces.

Asta te duce înapoi la problema inițială: voiai o singură ușă curată în fața unui serviciu, fără a transforma prima configurare într-un proiect complet de operații. Acum ai acea cale de lucru. Mai important, ai și modelul mental corect: HAProxy primește traficul mai întâi, îl trimite unde trebuie, și îți oferă o modalitate mai curată de a crește stiva pe un VPS auto-gestionat fără a pierde controlul asupra configurației.