Ubuntu VPS’de Docker Compose ile HAProxy Nasıl Kurulur

Bir VPS üzerinde bir web hizmetini doğrudan açığa çıkarmak kolaydır — ta ki temiz bir genel ön kapı isteyene, arka ucu daha sonra değiştirme özgürlüğüne veya kırık bir şeye trafik göndermeyi durdurmanın daha güvenli bir yoluna kadar. Bu noktada bir proxy, “büyük altyapı ekipleri için bir şey” gibi hissetmeyi bırakır ve pratik hale gelir.

HAProxy bu rol için iyi uyum sağlar. Bunu uygulamanızın önünde oturan trafik yöneticisi olarak düşünün: istekler önce HAProxy’ye ulaşır ve HAProxy bunların nereye gitmesi gerektiğine karar verir. Bundan yararlanmak için büyük bir kümeye ihtiyacınız yoktur. Tek bir Ubuntu 24.04 VPS üzerinde bile, internet ile gerçekten çalıştırdığınız hizmet arasında daha temiz bir kenar sağlar.

Bu kılavuz ilk dağıtımı kasıtlı olarak yapılandırılmış tutar: bir Ubuntu 24.04 VPS, Docker Compose, bir HAProxy konteyneri, bir demo arka ucu ve yönlendirmenin gerçekten çalıştığının kanıtı.

HAProxy Neden İhtiyaç Duymadan Önce Önemlidir

Bugün tek bir uygulamayı çalıştıran küçük bir VPS’i düşünün. Bir portta yanıt veriyor, site yükleniyor ve her şey iyi görünüyor. Sorun, istikrarlı bir genel giriş noktası istediğinizde, genel adresi değiştirmeden arka ucu daha sonra değiştirme seçeneğini istediğinizde veya başarısız bir hizmete trafik göndermeyi durdurabilen bir ön katman istediğinizde başlar. Uygulamayı doğrudan açığa çıkarmak şaşırtıcı derecede hızlı bir şekilde kırılgan hissettirir.

Bu gereksinimler hepsi aynı eksik katmana işaret eder: internet ile uygulamanız arasında kontrollü bir giriş noktası. HAProxy bu katmanı sağlar. İstemciler önce HAProxy’ye bağlanır ve HAProxy her isteğin sonra nereye gideceğine karar verir.

Bu ayrım, birden fazla sunucunuz olmadan bile yararlıdır. Size şimdi daha temiz bir genel kenar ve arka uç değiştirme, sağlık farkında yönlendirme ve HTTPS gibi sonraki değişikliklere daha güvenli bir yol sağlar. Kılavuzun geri kalanı bu deseni en basit çalışan biçiminde gösterir ve gerçek bir istek yolu ile doğrular.

HAProxy’nin Geri Kalanını Anlamayı Kolaylaştıran Hızlı HAProxy Terimleri

İlk HAProxy dağıtımını güvenle takip etmek için küçük bir kelime dağarcığına ihtiyacınız vardır. Aşağıdaki tablo bu kılavuzda önemli olan terimleri kapsamaktadır.

Bu kılavuz için, reverse proxy akılda tutulması gereken ilk zihinsel modeldir. HAProxy bir şeyin önünde oturur ve el değiştirmeyi kontrol eder. Load balancing, daha sonra birden fazla arka uç sunucusu eklediğinizde yararlı hale gelen genişletilmiş bir yetenektir.

Yapılandırmayı açtığınızda en önemli iki terim frontend ve backend‘dir. Frontend istemcinin geldiği yerdir. Backend HAProxy’nin isteği sonra gönderdiği yerdir. Health check önemlidir çünkü HAProxy’nin bir hedefin trafiği almayı bırakması gerektiğini fark etmesini sağlar.

HAProxy’nin İyi Olduğu Şeyler — ve Bu Kılavuzun Kasıtlı Olarak Atladığı Şeyler

Yığını bir ofis binası olarak hayal ederseniz, HAProxy ön masadır: trafik önce oraya gelir, doğru odaya yönlendirilir ve açıkça kullanılamayan bir odaya gönderilmesi durdurulur.

Bu kılavuzda, bu üç başlangıç düzeyinde ilgili işe çevrilir:

1. gelen HTTP isteklerini kabul et
2. bunları demo backend’e ilet
3. o backend’in trafik almaya devam etmek için yeterince sağlıklı olup olmadığını izle

Bir backend ile bile zaten yararlıdır çünkü uygulamanın önünde bir kontrollü genel kenar noktası sağlar.

Daha sonra, aynı desen temiz bir şekilde ölçeklendirilir. Backend’i değiştirebilir, daha fazla backend ekleyebilir, HTTPS tanıtabilir veya HAProxy’nin trafiği sadece bir tane yerine birden fazla hedefe yaymasını sağlayabilirsiniz. İlk geçişi öğretilebilir tutmak için, bu kılavuz HTTP modunda kalır ve kasıtlı olarak TLS sonlandırması, ACL’ler, hız sınırlaması, stick tabloları ve HA çiftlerini atlar. Bunların hepsi gerçek HAProxy konularıdır. Sadece ilk çalışan dağıtım için doğru başlangıç noktası değildir.

İnşa Ettiğiniz Şey ve Önce Neye İhtiyacınız Var

Dosyaları oluşturmadan önce, stack’in son şeklini görmek yardımcı olur. Bu kılavuzdaki dağıtım şöyle görünür:

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 burada ana yol çünkü ilk kurulumu tekrarlanabilir, görünür ve düzenlemesi kolay tutar. Birinci günde özel bir görüntü oluşturmak yerine, HAProxy yapılandırmasını ana bilgisayarda tutarsınız, bunu konteyner içine bağlarsınız ve tüm stack’i bir dosyadan başlatırsınız. Kendi kendini yöneten bir Ubuntu VPS’de — örneğin, bir AlexHost VPS’de — bu temiz bir uyum sağlar çünkü düzen incelemesi kolay kalır.

💡 İpucu: Bu kılavuz, Docker Compose artı bind-mounted haproxy.cfg kullanır. Bu, en şeffaf ilk kurulum yoludur çünkü proxy yapılandırmasını doğrudan bir görüntü oluşturma adımı eklemeden düzenleyebilirsiniz.

Başlamadan önce, bu temel öğelerin yerinde olduğundan emin olun:

• Ubuntu 24.04 VPS
• Docker Engine yüklü
• Docker Compose v2 docker compose aracılığıyla kullanılabilir
• Terminal erişimi ve Docker çalıştırma izni
• Ana bilgisayarda 80 numaralı port kullanılabilir
• UFW kullanırsanız veya sağlayıcı tarafı güvenlik duvarı kuralları varsa gelen HTTP’ye izin verilir

Önce Ubuntu sürümünüzü kontrol edin

lsb_release -a

Ardından, Docker ve modern Compose’un kullanılabilir olduğunu doğrulayın:

docker --version
docker compose version

Her iki komut da sürüm bilgisi döndürürse, konteyner çalışma zamanı tarafı hazırdır ve Docker kurulumuna sapmak yerine HAProxy’ye odaklanmış kalabilirsiniz.

Ardından, 80 numaralı portun zaten kullanımda olmadığından emin olun, sonra UFW’nin etkin olup olmadığını ve HTTP’ye zaten izin verilip verilmediğini kontrol edin:

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

✏️ NOT: ss kontrolünden hiçbir çıktı genellikle 80 numaralı portun boş olduğu anlamına gelir. nginx, apache2, caddy veya başka bir hizmetin zaten orada dinlediğini görürseniz, bunu önce düzeltin. Bu, daha sonra çok fazla kafa karışıklığından tasarruf eden on saniyelik bir ön kontrol adımıdır.

Yukarıdaki örnekte, sudo ufw status Status: active gösterir ve 80/tcp zaten izin listesinde mevcuttur. Bu nedenle sudo ufw allow 80/tcp yeni bir kural eklemek yerine Skipping adding existing rule döndürür. Bu çıktı normaldir ve basitçe güvenlik duvarı kuralının zaten yerinde olduğu anlamına gelir.

Proje Klasörünü ve Compose Dosyasını Oluşturun

Bu ilk dağıtımın ihtiyaç duyduğu iki dosya için küçük bir proje klasörü oluşturarak başlayın:

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

Bundan sonra, düzen mümkün olduğunca küçük olmalıdır:

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

Şimdi compose.yaml dosyasını oluşturun ve bu tam içeriği kullanın:

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

Bu dosya konteynerleri birbirine bağlar, ancak henüz HAProxy istek mantığını tanımlamaz. Docker’a hangi görüntüleri çalıştıracağını, hangi portları yayınlayacağını ve HAProxy yapılandırmasının ana bilgisayardan nereye monte edileceğini söyler.

Temiz bir ilk dağıtım için en önemli olan ayarlar şunlardır:

Burada bir ayrıntı daha önemlidir: Docker Compose otomatik olarak varsayılan bir ağ oluşturduğu için bu dosyada özel bir Docker ağı yoktur. Bu, proje içinde hizmet adı DNS’i sağlar, bu nedenle HAProxy arka uca demo:5678 olarak ekstra kablolama olmadan ulaşabilecektir.

⚠️ Uyarı: Port 80 ayrıcalıklı bir port olduğundan, sysctls satırı dekoratif değildir. Ana bilgisayar eşlemesini 8080:80 olarak değiştirmek, HAProxy hala içeride :80 öğesine bağlanıyorsa konteyner içindeki ayrıcalıklı port gereksinimini kaldırmaz.

Minimal haproxy.cfg Yazın ve Doğrulayın

Container bağlantısı yerinde olduğunda, HAProxy’nin trafiğin nerede geldiğini, nereye gitmesi gerektiğini ve arka uç sağlığının nasıl kontrol edileceğini belirten talimatlar gerekir. Sonra haproxy.cfg oluşturun:

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

Bu minimal bir konfigürasyondur, ancak atılacak bir şey değildir. log stdout format raw local0, Docker stdout’u kolayca yüzeyselleştirebileceği için container dostu günlüğe kaydetme seçimidir ve defaults içindeki mode http, tüm örneği HTTP modunda tutarak dinleyici ve arka uç davranışı tutarlı ve okunabilir kalır.

✏️ NOT: Bölüm dökümünden önce çağrılmaya değer bir ayrıntı vardır: balance roundrobin açıkça ayarlanmıştır çünkü daha yeni HAProxy sürümleri varsayılan arka uç algoritmasını random olarak değiştirmiş ve roundrobin ilk geçişte tahmin edilebilir şekilde öğretilmesi daha kolaydır.

Her bölümün düz İngilizce dökümü şöyledir:

Eksik olan bir şey fark edebilirsiniz: option forwardfor. Bu eksiklik temel yolda kasıtlıdır. Orijinal istemci IP’sini korumak daha sonra yararlıdır, ancak bu ilk dağıtım yönlendirme ve arka uç sağlığını kanıtlamakla ilgilidir, bu sinyali özellikle değerli kılmayan bir demo container ile başlık davranışını öğretmekle değil.

💡 İpucu: Tam yığını başlatmadan önce her zaman HAProxy konfigürasyonunu doğrulayın. Bu konfigürasyon arka ucu Compose hizmet adıyla (demo) referans aldığından, HAProxy doğrulama sırasında onu çözebildiği için önce o arka ucu başlatın.

Doğrulamayı aynı proje dizininden çalıştırın:

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

İkinci komut Configuration file is valid ile biterse, HAProxy’nin dosyayı doğru şekilde ayrıştırabileceğini ve herhangi bir canlı dinleyici başlamadan önce arka uç hedefini çözebileceğini zaten kanıtlamışsınız.

Stack’i Başlatın ve Proxy’nin Çalıştığını Kanıtlayın

Config doğrulandıktan sonra, stack’i detached modda başlatın:

Doğrulama adımı zaten demo‘yu başlattığı için, bu komut esas olarak HAProxy’yi ayağa kaldırır ve tam iki hizmet stack’ini uzlaştırır:

docker compose up -d

Ardından her iki container’ın da canlı olup olmadığını kontrol edin:

docker compose ps

Bu işlem görünümü yalnızca ilk kontrol noktasıdır. Docker’ın container’ları başlattığını doğrular, ancak henüz HAProxy’nin trafiği backend’e başarıyla yönlendirip yönlendirmediğini doğrulamaz. Sonraki istek gerçek veri yolunu doğrular.

Şimdi VPS’in kendisinden gerçek yönlendirme testini çalıştırın:

curl -i http://127.0.0.1

Başarı sinyali HTTP/1.1 200 OK artı yanıt gövdesi Hello from the HAProxy demo backend içeriyor. Bazı http-echo derlemeleri bu metni küçük bir HTML yanıtına sarabilir, bu nedenle tam biçimlendirmeden daha fazla gövde ifadesine odaklanın.

Tarayıcı düzeyinde kanıt istiyorsanız, başka bir makineden http://YOUR_SERVER_IP açın.

İkinci bir doğrulama yüzeyi için, VPS’den yerel istatistik sayfasını kontrol edin:

curl http://127.0.0.1:8404/stats

İstatistik sayfasında, en yararlı sinyaller http adlı bir frontend, demo_backend adlı bir backend, demo1 adlı bir sunucu satırı, UP olarak gösterilen durum ve genellikle L4OK in 0ms gibi son kontrol değeridir. Ayrıca bir küçük Docker nüansını aklınızda tutun: kısa sözdizimi depends_on başlangıç sırasını kontrol eder, ancak bir hizmetin sağlıklı hale gelmesini beklemez. Başlangıçtan hemen sonra ilk curl bir kez başarısız olursa, config’in yanlış olduğunu varsaymadan önce birkaç saniye bekleyin ve tekrar deneyin.

İşlem durumu ile gerçek başarı arasındaki fark tablo biçiminde anlaşılması daha kolaydır:

Yaygın İlk Çalıştırma Hataları ve Hızlı Çözümler

Kurulum hemen çalışmazsa, her iki dosyayı aynı anda yeniden yazma dürtüsüne direniş gösterin. Bu yığındaki çoğu ilk çalıştırma hatası öngörülebilir ve bir seferde bir değişkeni değiştirdiğinizde düzeltilmesi çok daha kolay hale gelir.

Hızlı tanı katmanı olarak bu matrisi kullanın:

• HAProxy hemen çıkıyor

  Olası neden: haproxy.cfg eksik.

  Hızlı çözüm: haproxy.cfg dosyasının compose.yaml dosyasının yanında olduğundan emin olun.

  Neden olur: Resmi imaj kullanıma hazır bir yapılandırma ile gelmez.

---

• Hata: /usr/local/etc/haproxy/haproxy.cfg açılamıyor diyor

  Olası neden: Yanlış bind-mount yolu.

  Hızlı çözüm: ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro tam olarak doğrulayın.

  Neden olur: HAProxy geçerli bir yapılandırma dosyası olmadan başlayamaz.

---

• Hata: 80 portunda İzin reddedildi diyor

  Olası neden: Ayrıcalıklı port bağlama sorunu.

  Hızlı çözüm: Compose’da net.ipv4.ip_unprivileged_port_start: “0” tutun veya HAProxy ve yayınlanan portu 8080‘e taşıyın.

  Neden olur: Konteyner root olmayan haproxy kullanıcısı olarak çalışır.

---

• Eşlemeyi 8080:80 olarak değiştirdiniz ve yine de bağlama hatası alıyorsunuz

  Olası neden: HAProxy hala konteyner içinde :80‘e bağlanıyor.

  Hızlı çözüm: 80 portundan uzaklaşırsanız hem ana bilgisayar eşlemesini hem de dahili bind satırını değiştirin.

  Neden olur: Ayrıcalıklı port kuralı konteyner içinde de geçerlidir.

---

• 80 portu zaten kullanımda

  Olası neden: Başka bir hizmet ana bilgisayar portuna sahip.

  Hızlı çözüm: ss kontrolünü yeniden çalıştırın ve çakışan hizmeti durdurun veya taşıyın.

  Neden olur: Yalnızca bir işlem aynı ana bilgisayar portunda dinleyebilir.

---

• Söz dizimi kontrolü bilinmeyen anahtar sözcük veya satıra özgü hatalar bildiriyor

  Olası neden: HAProxy yapılandırması yazım hatası.

  Hızlı çözüm: Söz dizimi kontrolünü yeniden çalıştırın ve bildirdiği tam satırı düzeltin.

  Neden olur: HAProxy’nin ayrıştırıcısı katı olup, bunu kasıtlı olarak kullandığınızda yardımcı olur.

---

• Konteynerler çalışıyor ama curl demo yanıtını döndürmüyor

  Olası neden: Yönlendirme yolu yanlış.

  Hızlı çözüm: default_backend demo_backend, server demo1 demo:5678 check ve demo hizmet adını yeniden kontrol edin.

  Neden olur: Çalışan bir konteyner doğru ön uç-arka uç yolunun kanıtı değildir.

---

• Yerel curl çalışıyor ama site dışarıdan erişilemiyor

  Olası neden: Güvenlik duvarı veya sağlayıcı güvenlik kuralı.

  Hızlı çözüm: UFW’da ve sağlayıcı tarafı güvenlik duvarında 80 portunu açın.

  Neden olur: Yerel yayımlama, genel erişim hala engellenmiş olsa bile çalışabilir.

⚠️ Uyarı: Bir seferde bir şey değiştirin. compose.yaml ve haproxy.cfg dosyalarını kör bir şekilde düzenlerseniz, hatanın bir dosya yolu sorunu, bir port sorunu veya bir yönlendirme sorunu olup olmadığını anlamak çok daha zor hale gelir.

Hızlı kanıta ihtiyacınız olduğunda, bu komutları yakında tutun:

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

Görüş açısından tanımaya değer en önemli üç uyarı deseni:

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

Küçük bir ilk dağıtımın güvence verici tarafı budur: hata şekilleri de genellikle küçüktür. Baştan başlamanız gerekmez. Hangi katmanın şikayet ettiğini belirlemeli ve önce o bir şeyi düzeltmelisiniz.

Kurulumdan Sonra Nereye Gitmeli

Tek backend demosunun çalışması halinde, mimari zaten kullanışlıdır. Bir sonraki gerçek adım, demo konteynerini aynı HAProxy yapısını koruyarak gerçek uygulamanızla değiştirmektir. Bundan sonra, HTTPS/TLS’yi ayrı bir takip adımı olarak ekleyin ve domain tabanlı yönlendirme ile ACL’leri bu ilk kuruluma aceleyle sokmak yerine ayrı konular olarak ele alın.

Birden fazla backend için hazır olduğunuzda, aynı desen açıkça anlamlı hale gelir:

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

Bind edilen bir konfigürasyon için güvenli düzenlemeler için önce doğrulayın ve ardından HAProxy’yi zarif bir şekilde yeniden yükleyin:

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: İstatistik sayfası bu kılavuzda kasıtlı olarak yalnızca yereldir. Bunu herkese açık hale getirirseniz, önce kimlik doğrulama ve erişim denetimleri ekleyin.

Bu sizi orijinal soruna geri getirir: bir hizmetin önünde temiz bir ön kapı istiyordunuz, ilk kurulumu tam bir operasyon projesine dönüştürmeden. Artık bu çalışan yola sahipsiniz. Daha da önemlisi, doğru zihinsel modele de sahipsiniz: HAProxy trafiği ilk olarak alır, onu ait olduğu yere iletir ve kendi kendini yöneten bir VPS’de yapıyı büyütmek için daha temiz bir yol sunar ve konfigürasyonun kontrolünü kaybetmezsiniz.