Cara Menginstal HAProxy dengan Docker Compose di Ubuntu VPS

Satu layanan web pada VPS mudah untuk expose secara langsung — sampai Anda menginginkan satu pintu depan publik yang bersih, kebebasan untuk menukar backend nanti, atau cara yang lebih aman untuk menghentikan pengiriman traffic ke sesuatu yang rusak. Itulah titik di mana proxy berhenti terasa seperti “sesuatu untuk tim infrastruktur besar” dan mulai terasa praktis.

HAProxy cocok untuk peran itu. Anggap saja sebagai manajer traffic yang duduk di depan aplikasi Anda: permintaan mengenai HAProxy terlebih dahulu, dan HAProxy memutuskan ke mana mereka harus pergi selanjutnya. Anda tidak perlu cluster besar untuk mendapat manfaat dari itu. Bahkan pada satu VPS Ubuntu 24.04, ini memberikan Anda tepi yang lebih bersih antara internet dan layanan yang sebenarnya Anda jalankan.

Panduan ini membuat deployment pertama dengan sengaja terstruktur: satu VPS Ubuntu 24.04, Docker Compose, satu container HAProxy, satu backend demo, dan bukti bahwa routing benar-benar berfungsi.

Mengapa HAProxy Penting Sebelum Anda Membutuhkannya

Bayangkan sebuah VPS kecil yang menjalankan satu aplikasi dengan baik hari ini. Aplikasi merespons di port tertentu, situs dimuat, dan semuanya terlihat baik. Masalah dimulai ketika Anda menginginkan titik masuk publik yang stabil, opsi untuk mengganti backend nanti tanpa mengubah alamat publik, atau lapisan depan yang dapat menghentikan pengiriman traffic ke layanan yang gagal. Mengekspos aplikasi secara langsung mulai terasa rapuh dengan cepat.

Semua persyaratan tersebut menunjuk ke lapisan yang hilang: titik masuk terkontrol antara internet dan aplikasi Anda. HAProxy menyediakan lapisan tersebut. Klien terhubung ke HAProxy terlebih dahulu, dan HAProxy memutuskan kemana setiap permintaan pergi selanjutnya.

Pemisahan tersebut berguna bahkan sebelum Anda memiliki beberapa server. Ini memberikan Anda tepi publik yang lebih bersih sekarang dan jalur yang lebih aman untuk perubahan nanti seperti penggantian backend, routing yang menyadari kesehatan, dan HTTPS. Sisa panduan menunjukkan pola tersebut dalam bentuk kerjanya yang paling sederhana dan memverifikasinya dengan jalur permintaan nyata.

Istilah HAProxy Cepat yang Membuat Sisa Panduan Ini Lebih Mudah

Anda hanya memerlukan kosakata kecil untuk mengikuti deployment HAProxy pertama dengan percaya diri. Tabel di bawah mencakup istilah yang penting dalam panduan ini.

Untuk panduan ini, reverse proxy adalah model mental pertama yang harus diingat. HAProxy duduk di depan sesuatu yang lain dan mengontrol penyerahan. Load balancing adalah kemampuan yang diperluas yang menjadi berguna ketika Anda menambahkan beberapa server backend nanti.

Dua istilah yang paling penting setelah Anda membuka konfigurasi adalah frontend dan backend. Frontend adalah tempat klien tiba. Backend adalah tempat HAProxy mengirimkan permintaan selanjutnya. Health check penting karena memungkinkan HAProxy menyadari kapan target harus berhenti menerima lalu lintas.

Apa yang HAProxy Bagus Lakukan — dan Apa yang Panduan Ini Sengaja Lewatkan

Jika Anda membayangkan stack Anda sebagai gedung kantor, HAProxy adalah meja depan: traffic tiba di sana terlebih dahulu, diarahkan ke ruangan yang tepat, dan berhenti dikirim ke ruangan yang jelas tidak tersedia.

Dalam panduan ini, itu diterjemahkan menjadi tiga pekerjaan yang relevan untuk pemula:

1. terima permintaan HTTP yang masuk
2. teruskan ke backend demo
3. pantau apakah backend tersebut cukup sehat untuk terus menerima traffic

Itu sudah berguna dengan satu backend karena memberikan Anda satu edge publik yang terkontrol di depan aplikasi.

Nanti, pola yang sama berkembang dengan bersih. Anda dapat mengganti backend, menambahkan lebih banyak backend, memperkenalkan HTTPS, atau membiarkan HAProxy menyebarkan traffic di beberapa target alih-alih hanya satu. Untuk membuat lintasan pertama dapat diajarkan, panduan ini tetap dalam mode HTTP dan sengaja melewatkan TLS termination, ACLs, rate limiting, stick tables, dan HA pairs. Itu semua adalah topik HAProxy yang nyata. Mereka hanya bukan titik awal yang tepat untuk deployment pertama yang berfungsi.

Apa yang Anda Bangun dan Apa yang Anda Butuhkan Terlebih Dahulu

Sebelum membuat file, membantu untuk melihat bentuk akhir dari stack. Deployment dalam panduan ini terlihat seperti ini:

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 adalah jalur utama di sini karena menjaga instalasi pertama dapat direproduksi, terlihat, dan mudah diedit. Alih-alih membangun image kustom pada hari pertama, Anda menyimpan konfigurasi HAProxy di host, memasangnya ke dalam container, dan memulai seluruh stack dari satu file. Pada VPS Ubuntu yang dikelola sendiri — misalnya, VPS AlexHost — itu adalah kecocokan yang bersih karena layoutnya tetap mudah diperiksa.

💡 Tip: Panduan ini menggunakan Docker Compose plus bind-mounted haproxy.cfg dengan sengaja. Ini adalah jalur instalasi pertama yang paling transparan karena Anda dapat mengedit konfigurasi proxy secara langsung tanpa menambahkan langkah build image.

Sebelum Anda memulai, pastikan Anda memiliki dasar-dasar ini:

• Ubuntu 24.04 VPS
• Docker Engine terinstal
• Docker Compose v2 tersedia melalui docker compose
• Akses terminal dan izin untuk menjalankan Docker
• Port 80 tersedia di host
• HTTP inbound diizinkan jika Anda menggunakan UFW atau aturan firewall sisi penyedia

Pertama, periksa versi Ubuntu Anda

lsb_release -a

Selanjutnya, konfirmasi Docker dan Compose modern tersedia:

docker --version
docker compose version

Jika kedua perintah mengembalikan informasi versi, sisi runtime container siap dan Anda dapat tetap fokus pada HAProxy alih-alih mengalihkan perhatian ke instalasi Docker.

Selanjutnya, pastikan port 80 tidak sudah digunakan, kemudian periksa apakah UFW aktif dan apakah HTTP sudah diizinkan:

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

✏️ CATATAN: Tidak ada output dari pemeriksaan ss biasanya berarti port 80 bebas. Jika Anda melihat nginx, apache2, caddy, atau layanan lain yang sudah mendengarkan di sana, perbaiki itu terlebih dahulu. Ini adalah langkah pra-penerbangan sepuluh detik yang menghemat banyak kebingungan nanti.

Dalam contoh di atas, sudo ufw status menunjukkan Status: active, dan 80/tcp sudah ada dalam daftar izin. Itulah mengapa sudo ufw allow 80/tcp mengembalikan Skipping adding existing rule alih-alih menambahkan yang baru. Output itu normal dan hanya berarti aturan firewall sudah ada.

Buat Folder Proyek dan File Compose

Mulai dengan membuat folder proyek kecil untuk dua file yang dibutuhkan deployment pertama ini:

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

Setelah itu, tata letaknya harus sekecil mungkin:

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

Sekarang buat compose.yaml dan gunakan konten yang tepat ini:

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

File ini menghubungkan container bersama-sama, tetapi belum mendefinisikan logika permintaan HAProxy. File ini memberi tahu Docker image mana yang akan dijalankan, port mana yang akan dipublikasikan, dan di mana konfigurasi HAProxy akan dipasang dari host.

Pengaturan berikut adalah yang paling penting untuk deployment pertama yang bersih:

Satu detail lagi penting di sini: tidak ada jaringan Docker kustom dalam file ini karena Docker Compose membuat jaringan default secara otomatis. Itu memberikan Anda DNS nama layanan di dalam proyek, itulah sebabnya HAProxy akan dapat menjangkau backend sebagai demo:5678 tanpa kabel ekstra.

⚠️ Peringatan: Port 80 adalah port istimewa, jadi baris sysctls bukan dekoratif. Mengubah pemetaan host menjadi 8080:80 tidak menghilangkan persyaratan port istimewa di dalam container jika HAProxy masih mengikat ke :80 secara internal.

Tulis dan Validasi haproxy.cfg Minimal

Dengan wiring container sudah ada, HAProxy masih memerlukan instruksi untuk tempat traffic tiba, kemana traffic harus pergi, dan bagaimana kesehatan backend diperiksa. Buat haproxy.cfg selanjutnya:

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

Ini adalah config minimal, tetapi bukan config yang dapat dibuang. log stdout format raw local0 adalah pilihan logging yang ramah container karena Docker dapat menampilkan stdout dengan mudah, dan mode http dalam defaults membuat seluruh contoh tetap dalam mode HTTP sehingga perilaku listener dan backend tetap konsisten dan mudah dibaca.

✏️ CATATAN: Satu detail layak disoroti sebelum rincian bagian: balance roundrobin diatur secara eksplisit karena versi HAProxy yang lebih baru mengubah algoritma backend default menjadi random, dan roundrobin lebih mudah diajarkan secara dapat diprediksi pada lintasan pertama.

Berikut adalah rincian bahasa Inggris biasa dari setiap bagian:

Anda mungkin memperhatikan satu hal yang hilang: option forwardfor. Kelalaian itu disengaja dalam jalur dasar. Mempertahankan IP klien asli berguna nanti, tetapi deployment pertama ini tentang membuktikan routing dan kesehatan backend, bukan mengajarkan perilaku header dengan container demo yang tidak membuat sinyal itu sangat berharga.

💡 Tip: Selalu validasi config HAProxy sebelum Anda memulai stack lengkap. Karena config ini merujuk ke backend dengan nama layanan Compose (demo), mulai backend itu terlebih dahulu sehingga HAProxy dapat menyelesaikannya selama validasi.

Jalankan validasi dari direktori proyek yang sama:

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

Jika perintah kedua berakhir dengan Configuration file is valid, Anda telah membuktikan bahwa HAProxy dapat mengurai file dengan benar dan menyelesaikan target backend sebelum listener live apa pun dimulai.

Mulai Stack dan Buktikan Proxy Berfungsi

Setelah konfigurasi divalidasi, mulai stack dalam mode terpisah:

Karena langkah validasi sudah memulai demo, perintah ini terutama membawa HAProxy dan merekonsiliasi stack dua layanan lengkap:

docker compose up -d

Kemudian periksa apakah kedua kontainer aktif:

docker compose ps

Tampilan proses itu hanya titik pemeriksaan pertama. Ini mengkonfirmasi bahwa Docker memulai kontainer, tetapi belum bahwa HAProxy berhasil merutekan lalu lintas ke backend. Permintaan berikutnya memverifikasi jalur data aktual.

Sekarang jalankan tes perutean aktual dari VPS itu sendiri:

curl -i http://127.0.0.1

Sinyal kesuksesan adalah HTTP/1.1 200 OK ditambah badan respons yang berisi Hello from the HAProxy demo backend. Beberapa build http-echo membungkus teks itu dalam respons HTML kecil, jadi fokus pada frasa badan lebih dari pemformatan yang tepat.

Jika Anda menginginkan bukti tingkat browser, buka http://YOUR_SERVER_IP dari mesin lain.

Untuk permukaan validasi kedua, periksa halaman statistik khusus lokal dari VPS:

curl http://127.0.0.1:8404/stats

Di halaman statistik, sinyal paling berguna adalah frontend bernama http, backend bernama demo_backend, baris server bernama demo1, status ditampilkan sebagai UP, dan biasanya nilai pemeriksaan terakhir seperti L4OK in 0ms. Juga ingat satu nuansa Docker kecil: depends_on sintaks pendek mengontrol urutan startup, tetapi tidak menunggu layanan menjadi sehat. Jika curl pertama gagal sekali tepat setelah startup, tunggu beberapa detik dan coba lagi sebelum menganggap konfigurasi salah.

Perbedaan antara status proses dan kesuksesan nyata lebih mudah diingat dalam bentuk tabel:

Kesalahan Umum Saat Pertama Kali Menjalankan dan Perbaikan Cepat

Jika setup tidak berfungsi segera, tahan keinginan untuk menulis ulang kedua file sekaligus. Sebagian besar kegagalan pertama kali pada stack ini dapat diprediksi, dan menjadi jauh lebih mudah untuk diperbaiki ketika Anda mengubah satu variabel pada satu waktu.

Gunakan matriks ini sebagai lapisan diagnosis cepat:

• HAProxy keluar segera

  Kemungkinan penyebab: haproxy.cfg hilang.

  Perbaikan cepat: Pastikan haproxy.cfg ada di sebelah compose.yaml.

  Mengapa ini terjadi: Image resmi tidak dilengkapi dengan config yang siap digunakan.

---

• Error mengatakan tidak dapat membuka /usr/local/etc/haproxy/haproxy.cfg

  Kemungkinan penyebab: Path bind-mount salah.

  Perbaikan cepat: Verifikasi ./haproxy.cfg:/usr/local/etc/haproxy/haproxy.cfg:ro dengan tepat.

  Mengapa ini terjadi: HAProxy tidak dapat dimulai tanpa file config yang valid.

---

• Error mengatakan Permission denied pada port 80

  Kemungkinan penyebab: Masalah binding port istimewa.

  Perbaikan cepat: Pertahankan net.ipv4.ip_unprivileged_port_start: “0” di Compose, atau pindahkan HAProxy dan port yang dipublikasikan ke 8080.

  Mengapa ini terjadi: Container berjalan sebagai pengguna non-root haproxy.

---

• Anda mengubah mapping menjadi 8080:80 dan masih mendapat error bind

  Kemungkinan penyebab: HAProxy masih bind ke :80 di dalam container.

  Perbaikan cepat: Ubah baik mapping host maupun baris bind internal jika Anda pindah dari port 80.

  Mengapa ini terjadi: Aturan port istimewa berlaku di dalam container juga.

---

• Port 80 sudah digunakan

  Kemungkinan penyebab: Layanan lain memiliki port host.

  Perbaikan cepat: Jalankan kembali pemeriksaan ss dan hentikan atau pindahkan layanan yang bertentangan.

  Mengapa ini terjadi: Hanya satu proses yang dapat mendengarkan pada port host yang sama.

---

• Pemeriksaan sintaks melaporkan unknown keyword atau error spesifik baris

  Kemungkinan penyebab: Typo config HAProxy.

  Perbaikan cepat: Jalankan kembali pemeriksaan sintaks dan perbaiki baris yang dilaporkannya.

  Mengapa ini terjadi: Parser HAProxy ketat, yang membantu setelah Anda menggunakannya dengan sengaja.

---

• Container berjalan, tetapi curl tidak mengembalikan respons demo

  Kemungkinan penyebab: Path routing salah.

  Perbaikan cepat: Periksa kembali default_backend demo_backend, server demo1 demo:5678 check, dan nama layanan demo.

  Mengapa ini terjadi: Container yang berjalan bukan bukti path frontend-ke-backend yang benar.

---

• curl lokal berfungsi tetapi situs tidak dapat diakses dari luar

  Kemungkinan penyebab: Firewall atau aturan keamanan penyedia.

  Perbaikan cepat: Buka port 80 di UFW dan firewall sisi penyedia apa pun.

  Mengapa ini terjadi: Penerbitan lokal dapat berfungsi bahkan ketika akses publik masih diblokir.

⚠️ Peringatan: Ubah satu hal pada satu waktu. Jika Anda mengedit compose.yaml dan haproxy.cfg secara membabi buta, Anda membuat jauh lebih sulit untuk menentukan apakah kegagalan adalah masalah path file, masalah port, atau masalah routing.

Ketika Anda membutuhkan bukti cepat, simpan perintah-perintah ini di dekat:

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

Ini adalah tiga pola alert yang paling layak dikenali sekilas:

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

Itulah bagian yang meyakinkan dari deployment pertama yang kecil: bentuk kegagalan biasanya juga kecil. Anda tidak perlu memulai dari awal. Anda perlu mengidentifikasi layer mana yang mengeluh dan memperbaiki satu hal itu terlebih dahulu.

Ke Mana Pergi Setelah Instalasi

Setelah demo satu backend berfungsi, arsitektur sudah berguna. Langkah nyata berikutnya adalah mengganti container demo dengan aplikasi aktual Anda sambil mempertahankan struktur HAProxy yang sama. Setelah itu, tambahkan HTTPS/TLS sebagai langkah lanjutan terpisah, dan perlakukan routing berbasis domain plus ACL sebagai topik terpisah daripada terburu-buru memasukkannya ke instalasi pertama ini.

Ketika Anda siap untuk lebih dari satu backend, pola yang sama menjadi terlihat bermakna:

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

Untuk edit aman pada config yang di-bind mount, validasi terlebih dahulu kemudian reload HAProxy dengan lancar:

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

📝 Catatan: Halaman stats sengaja hanya lokal dalam panduan ini. Jika Anda pernah mengeksposnya secara publik, tambahkan autentikasi dan kontrol akses terlebih dahulu.

Itu membawa Anda kembali ke masalah asli: Anda menginginkan satu pintu depan yang bersih di depan layanan, tanpa mengubah setup pertama menjadi proyek operasi penuh. Anda sekarang memiliki jalur kerja itu. Yang lebih penting, Anda juga memiliki model mental yang tepat: HAProxy menerima traffic terlebih dahulu, meneruskannya ke tempat yang sesuai, dan memberi Anda cara yang lebih bersih untuk mengembangkan stack pada VPS yang dikelola sendiri tanpa kehilangan kontrol konfigurasi.