Ubuntu VPS üzerinde Docker Compose ile HAProxy Nasıl Kurulur

Bir VPS üzerinde tek 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 bozuk bir şeye trafik göndermeyi durdurmanın daha güvenli bir yoluna kadar. Proxy’nin “büyük altyapı ekipleri için bir şey” hissi vermekten pratik hissi vermesine geçtiği nokta burası.

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

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

HAProxy Neden İhtiyaç Duymadan Önce Önemlidir

Küçük bir VPS’de bugün bir uygulamanın sorunsuz çalıştığını hayal edin. Bir portta yanıt verir, site yüklenir ve her şey iyi görünür. Karmaşıklık, istikrarlı bir genel giriş noktası istediğinizde, genel adresi değiştirmeden arka ucu daha sonra değiştirme seçeneği 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 hissetmeye başlar.

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 olmasından önce bile yararlıdır. Size şimdi daha temiz bir genel kenar sağlar ve arka uç değişimi, sağlık bilincine sahip yönlendirme ve HTTPS gibi sonraki değişikliklere daha güvenli bir yol açar. Kılavuzun geri kalanı bu deseni en basit çalışan biçiminde gösterir ve bunu 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 kapsar.

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

Yapılandırmayı açtığınızda en önemli olan 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ıç seviyesi işe çevrilir:

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

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çeklenir. 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ğildirler.

İ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 yoldur çü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, onu kapsayıcıya bağlarsınız ve tüm stack’i bir dosyadan başlatırsınız. Kendi kendine yönetilen 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’u ve bağlı bir haproxy.cfg dosyasını kasıtlı olarak kullanır. Bu en şeffaf ilk kurulum yoludur çünkü görüntü oluşturma adımı eklemeden proxy yapılandırmasını doğrudan düzenleyebilirsiniz.

Başlamadan önce, şu 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ıyorsanı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

Sonra, 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, kapsayıcı çalışma zamanı tarafı hazırdır ve Docker kurulumuna sapıtmak yerine HAProxy’ye odaklanmaya devam edebilirsiniz.

Sonra, 80 numaralı portun zaten kullanımda olmadığından emin olun, ardından 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 çıktı yok 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, önce bunu düzeltin. Bu on saniyelik bir ön kontrol adımıdır ve daha sonra çok fazla kafa karışıklığını önler.

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 ayarlar şunlardır:

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

⚠️ Uyarı: Port 80 ayrıcalıklı bir porttur, bu nedenle sysctls satırı dekoratif değildir. Ana bilgisayar eşlemesini 8080:80 olarak değiştirmek, HAProxy hala içinde :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 kablolama yerinde olduğunda, HAProxy’nin trafiğin nereye geldiğini, nereye gitmesi gerektiğini ve arka uç sağlığının nasıl kontrol edileceğini söyleyen 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üzeyleyebildiğ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ı 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ştir ve roundrobin ilk geçişte tahmin edilebilir şekilde öğretilmesi daha kolaydır.

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

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

💡 İ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, doğrulama sırasında HAProxy’nin onu çözebilmesi için önce bu 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 modunda başlatın:

Doğrulama adımı zaten demo‘yu başlattığı için, bu komut esas olarak HAProxy’yi başlatı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ü sadece 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 yapıları bu metni küçük bir HTML yanıtında 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 bir 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 daha kolay anlaşılı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üzeltmesi çok daha kolay hale gelir.

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

• HAProxy hemen çıkıyor

  Muhtemel 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 görüntü hazır kullanıma uygun bir yapılandırmayla gelmez.

---

• Hata /usr/local/etc/haproxy/haproxy.cfg dosyasını açamadığını söylüyor

  Muhtemel neden: Yanlış bind-mount yolu.

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

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

---

• Hata 80 portunda İzin reddedildi diyor

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

  Hızlı çözüm: Compose’da net.ipv4.ip_unprivileged_port_start: “0” tutun veya hem HAProxy’yi hem de yayınlanan portu 8080 olarak 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

  Muhtemel neden: HAProxy hala konteyner içinde :80 portuna 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

  Muhtemel 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 kelime veya satıra özgü hatalar bildiriyor

  Muhtemel 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ıdır, bu da bunu kasıtlı olarak kullandığınızda yardımcı olur.

---

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

  Muhtemel 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 bir ön uç-arka uç yolunun kanıtı değildir.

---

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

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

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

  Neden olur: Yerel yayın, 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 mu, bir port sorunu mu yoksa bir yönlendirme sorunu mu olduğunu 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üşte 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üven verici kısmı budur: hata şekilleri de genellikle küçüktür. Baştan başlamanıza gerek yok. Hangi katmanın şikayet ettiğini belirlemeli ve önce o bir şeyi düzeltmelisiniz.

Kurulumdan Sonra Nereye Gitmeli

Tek backend demo çalıştığında, mimari zaten kullanışlıdır. 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 config dosyasında 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 hiç halka açık hale getirirseniz, önce kimlik doğrulama ve erişim denetimleri ekleyin.

Bu sizi orijinal soruna geri getirir: bir hizmetin önünde bir temiz ö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 konfigürasyonun kontrolünü kaybetmeden self-managed bir VPS’de yığını büyütmek için daha temiz bir yol sağlar.