Belajar Nginx - Troubleshooting & Debugging NGINX

#Pendahuluan

Pada titik tertentu, produksi akan berulah: website tiba-tiba 502, upload gagal dengan 413, atau halaman menolak akses dengan 403. Episode 19 ini membekali kalian alat diagnostik dan mental model untuk troubleshooting NGINX dengan cepat dan sistematis.

Kalian akan memakai nginx -t dan nginx -T untuk memvalidasi dan membedah konfigurasi, membaca error log termasuk level debug, serta memahami penyebab dan solusi error code paling populer. Ini episode yang akan menyelamatkan kalian di jam 3 pagi saat produksi down.

#Perintah Diagnostik Utama

#nginx -t: Test Syntax

Perintah pertama untuk setiap kecurigaan konfigurasi:

sudo nginx -t

nginx -t memeriksa semua file konfigurasi dan menampilkan lokasi error lengkap dengan nama file dan nomor baris jika ada yang salah.

#nginx -T: Dump Konfigurasi Gabungan

Kadang konfigurasi terpecah di banyak file dan error tidak terlihat. nginx -T menggabungkan semuanya:

sudo nginx -T | grep -n "server_name" | head -20

nginx -T menampilkan seluruh konfigurasi setelah semua include diproses — termasuk konfigurasi dari modul lain yang mungkin tidak kalian ingat pernah menulis.

#Membaca dan Menganalisis Error Log

#Level Log dan Lokasi

Error log menampung semua masalah serius:

sudo tail -50 /var/log/nginx/error.log

Level log mulai dari debug (paling detail) sampai emerg. Default distro biasanya warn atau error. Saat troubleshooting mendalam, naikkan level sementara:

error_log /var/log/nginx/error.log debug;

Dengan debug, NGINX menulis detail sangat lengkap: proses memilih location, negosiasi upstream, dan event koneksi. Aktifkan hanya saat debugging, lalu kembalikan ke level normal karena debug sangat boros disk.

#Troubleshooting HTTP Error Codes Populer

#502 Bad Gateway

NGINX tidak bisa menghubungi backend. Penyebab umum:

• Backend down atau port salah pada proxy_pass.
• Backend hanya mendengarkan di localhost tapi NGINX mengarah ke IP lain.
• Selisih protokol: proxy_pass ke HTTPS tapi backend HTTP.

Cek dengan curl dan lihat error log:

curl -I http://localhost:3000
tail -20 /var/log/nginx/error.log

curl -I http://localhost:3000 menguji backend langsung. Jika curl gagal, masalahnya di backend, bukan NGINX.

#504 Gateway Timeout

Backend menerima request tapi terlalu lambat merespons. Naikkan timeout atau perbaiki backend:

location / {
    proxy_pass http://backend_app;
    proxy_read_timeout 90s;
    proxy_connect_timeout 10s;
}

Periksa juga query database yang lambat dan endpoint yang melakukan kerja berat tanpa batas waktu.

#403 Forbidden

NGINX berhasil menemukan file tapi tidak boleh membacanya. Penyebab umum:

• Permission folder atau file salah: NGINX berjalan sebagai user www-data dan harus bisa masuk ke seluruh path menuju file.
• index tidak ditemukan di direktori tanpa autoindex.
• Terkena deny all; dari kontrol akses.

sudo -u www-data ls -la /var/www/example/

Jika user www-data tidak bisa membaca folder, set owner dan permission dengan chown dan chmod.

#413 Request Entity Too Large

Upload ditolak karena melebihi client_max_body_size:

server {
    client_max_body_size 50M;
}

Sesuaikan dengan batas upload aplikasi, misalnya client_max_body_size 50M;.

#500 Internal Server Error

Error yang paling samar. Penyebab NGINX murni biasanya:

• Rewrite loop: dua aturan rewrite atau redirect yang saling mengarahkan tanpa akhir.
• Kegagalan memuat modul atau worker.

Lihat error log untuk menemukan penyebab pasti:

sudo tail -50 /var/log/nginx/error.log

Jika 500 berasal dari backend (PHP-FPM, aplikasi), error log aplikasi adalah sumber utamanya.

#Alur Debugging yang Sistematis

#Empat Langkah Kunci

Saat ada masalah, ikuti urutan ini:

1. Uji sintaks: nginx -t.
2. Baca error log: tail -f /var/log/nginx/error.log.
3. Reproduksi dengan curl dan amati respons serta header.
4. Pisahkan lapisan: apakah masalah di NGINX, backend, atau jaringan.

Pisahkan lapisan dengan menguji backend langsung. Jika backend sehat tapi NGINX gagal, fokuskan debugging di konfigurasi proxy. Jika keduanya sehat tapi klien masih error, periksa DNS dan network.

#Penutup

Episode 19 membuat kalian siap menghadapi produksi yang berulah: kalian menguasai nginx -t dan nginx -T, membaca error log hingga level debug, dan memahami penyebab utama 502, 504, 403, 413, serta 500.

Inti yang harus dibawa pulang:

• nginx -t memvalidasi sintaks; nginx -T menampilkan konfigurasi gabungan.
• Level debug pada error log membongkar detail pemrosesan request.
• 502 berarti backend tidak bisa dihubungi; cek langsung dengan curl.
• 504 berarti backend lambat; naikkan timeout atau perbaiki backend.
• 403 biasanya permission; 413 karena client_max_body_size.
• 500 sering dari rewrite loop — selalu buka error log untuk penyebab pasti.

Di episode 20 selanjutnya kita akan membahas studi kasus complete production-grade NGINX gateway architecture — merancang gateway enterprise dari HTTPS dan security perimeter, observability, lapisan performa, hingga upstream routing dengan fallback maintenance, lengkap dengan checklist kesiapan produksi.