Biasakan nginx -t Sebelum Reload agar Typo Config Tidak Bikin Situs Down

Kamu menambah satu baris di server block, lupa titik koma, lalu langsung menjalankan systemctl reload nginx. Kadang perintahnya gagal dengan pesan yang tidak jelas. Kadang tidak terjadi apa-apa dan kamu mengira config baru sudah jalan. Yang paling repot: kalau yang dijalankan restart, Nginx berhenti dan semua situs di server itu ikut tidak bisa diakses. Kebiasaan yang mencegah semua ini sederhana. Jalankan nginx -t dulu, baru reload, lalu cek apakah service benar-benar memakai config yang baru.

Reload gagal dan restart gagal itu beda akibatnya

Nginx berjalan dengan satu proses master dan beberapa proses worker. Master membaca config dan mengatur worker, sedangkan worker yang melayani request pengunjung. Saat kamu reload, master membaca ulang semua file config. Kalau config valid, master menyalakan worker baru dengan config baru. Worker lama menyelesaikan koneksi yang masih berjalan, lalu keluar. Kalau config tidak valid, master menulis error ke log dan tetap memakai worker lama. Situs biasanya tetap hidup, tapi masih memakai config lama. Dari sinilah muncul keluhan klasik: sudah reload, kok perubahannya tidak terlihat. Restart berbeda. Restart menghentikan Nginx dulu, baru menyalakannya lagi. Kalau config rusak, proses start gagal dan Nginx tetap mati. Tidak ada config lama yang bisa dipakai sebagai cadangan. Ada satu jebakan lagi. Config rusak yang tertinggal di disk setelah reload gagal tidak langsung terasa. Masalahnya baru muncul saat ada yang restart service atau server reboot, bisa lama setelah perubahan dibuat, dan orang yang menangani belum tentu tahu siapa yang mengubah apa. Di meja support, keluhan seperti situs mati setelah reboot VPS sering berujung ke file config yang sudah lama rusak.

Menjalankan nginx -t dengan benar

nginx -t menguji syntax config dan semua file yang di-include, tanpa mengganggu proses yang sedang berjalan. Pengujian ini juga mencoba membuka file yang direferensikan config, misalnya sertifikat SSL dan file include. Jadi jalankan dengan sudo. Tanpa root, kamu bisa mendapat error permission yang sebenarnya bukan masalah config. Pastikan juga binary dan file config yang diuji memang yang dipakai service. Di server dengan panel kontrol, build custom, atau beberapa instalasi Nginx, path-nya bisa berbeda dari default.

BASH

# cek binary yang terpanggil dan path config default build ini
command -v nginx
sudo nginx -V 2>&1 | tr ' ' '
' | grep conf-path

# uji syntax dan semua file yang di-include
sudo nginx -t

# tampilkan config gabungan semua include, lalu cari server_name
sudo nginx -T 2>/dev/null | grep -n 'server_name'

nginx -T (huruf besar) menjalankan test yang sama, lalu mencetak seluruh config hasil gabungan semua include. Perintah ini berguna untuk memastikan file yang baru kamu edit benar-benar ikut terbaca. Sering kali file sudah diedit dengan benar, tapi letaknya di folder yang tidak di-include, atau ekstensinya tidak cocok dengan pola include. Kalau config utama ada di lokasi lain, uji dengan sudo nginx -t -c /path/ke/nginx.conf. Kalau Nginx berjalan di dalam container, jalankan test di dalam container itu, misalnya lewat docker exec. Binary dan config di host belum tentu sama dengan yang ada di dalam container.

Membaca output nginx -t

Kalau config valid, Nginx menampilkan dua baris: syntax is ok dan test is successful. Kalau ada masalah, bentuknya kira-kira seperti ini.

TEXT

# contoh format output
nginx: [emerg] unexpected "}" in /etc/nginx/sites-enabled/example.conf:24
nginx: configuration file /etc/nginx/nginx.conf test failed

Bagian terpenting adalah path file dan nomor baris. Tapi nomor baris itu tidak selalu menunjuk lokasi typo yang sebenarnya. Contohnya titik koma yang hilang. Nginx akan membaca baris berikutnya sebagai lanjutan argumen direktif sebelumnya, jadi error baru muncul satu atau beberapa baris setelahnya. Kalau baris yang ditunjuk terlihat benar, periksa beberapa baris di atasnya. Beberapa pesan yang sering muncul:

unknown directive: biasanya typo nama direktif, atau direktif dari modul yang tidak terpasang di build tersebut.
is not terminated by ";": titik koma hilang.
unexpected "}" atau unexpected end of file: kurung kurawal tidak seimbang.
cannot load certificate: path sertifikat SSL salah atau filenya belum ada.
host not found in upstream: nama host di proxy_pass atau blok upstream tidak bisa di-resolve saat config dibaca.

Perhatikan juga baris [warn]. Test tetap dianggap berhasil, tapi warning seperti conflicting server name berarti ada dua server block dengan nama yang sama, dan salah satunya diabaikan. Situsnya mungkin tetap jalan, tapi melayani isi dari blok yang tidak kamu harapkan. Yang perlu diingat, nginx -t hanya memeriksa apakah config bisa dibaca dan dimuat. Ia tidak tahu apakah root mengarah ke folder yang benar, apakah proxy_pass menunjuk port backend yang benar, atau apakah server_name ada typo. Semua itu syntax-nya valid, tapi hasilnya tetap salah. Karena itu, verifikasi setelah reload tetap perlu.

Urutan aman: test, reload, lalu verifikasi

Gabungkan test dan reload dengan &&. Reload hanya jalan kalau test selesai dengan exit code 0. Kalau test gagal, reload tidak dijalankan dan error-nya langsung terlihat di layar. Untuk membuktikan reload benar-benar terjadi, lihat PID worker. Saat reload berhasil, PID master tetap sama, sedangkan worker diganti dengan proses baru yang PID dan waktu mulainya berbeda. Kalau setelah reload PID worker masih sama persis, berarti config baru belum dipakai.

BASH

# catat PID dan waktu mulai proses sebelum reload
ps -C nginx -o pid,ppid,lstart,cmd

# reload hanya jalan kalau test lolos
sudo nginx -t && sudo systemctl reload nginx

# worker harus baru; master tetap sama
ps -C nginx -o pid,ppid,lstart,cmd
systemctl is-active nginx
sudo journalctl -u nginx --since '5 minutes ago' --no-pager
sudo tail -n 20 /var/log/nginx/error.log

# uji langsung ke server lokal, tanpa lewat DNS atau CDN
curl -sI -H 'Host: example.com' http://127.0.0.1/

Sesaat setelah reload, worker lama bisa masih terlihat dengan keterangan is shutting down di kolom cmd. Itu normal. Worker lama sedang menyelesaikan koneksi yang masih aktif. Kalau prosesnya bertahan lama, biasanya ada koneksi panjang seperti websocket atau download besar yang belum selesai. Lokasi error log mengikuti direktif error_log di config kamu, jadi sesuaikan path di atas. Untuk situs HTTPS, uji dengan curl -skI --resolve example.com:443:127.0.0.1 https://example.com/ supaya SNI dan sertifikat yang dipilih sesuai domain. Ganti example.com dengan domain yang baru kamu ubah, lalu pastikan status code dan header-nya sesuai harapan. Kalau perubahanmu menambah header atau aturan baru, misalnya rate limiting, cek perilakunya langsung. Langkahnya ada di Cara Cek Rate Limiting Nginx Benar-Benar Aktif di wp-login.php. Kalau ingin tahu persis perintah apa yang dijalankan systemd saat reload dan start, lihat dengan systemctl cat nginx. Di beberapa paket, unit-nya sudah menjalankan test sebelum start. Di paket lain tidak. Jangan berasumsi, cek di server kamu sendiri.

Kalau Nginx sudah terlanjur mati

Jangan mengulang restart berkali-kali. Selama config masih rusak, hasilnya akan sama. Langkah yang lebih aman:

Jalankan sudo nginx -t untuk melihat file dan baris yang bermasalah.
Perbaiki baris tersebut. Kalau penyebabnya belum jelas dan situs lain harus segera hidup, pindahkan sementara file config yang baru diubah ke luar folder include.
Jalankan sudo nginx -t lagi sampai lolos.
Start service dengan sudo systemctl start nginx, lalu cek dengan systemctl status nginx dan curl seperti di atas.

Hati-hati dengan file backup. Di Debian dan Ubuntu, nginx.conf biasanya meng-include sites-enabled/*, artinya semua file di folder itu ikut dibaca, termasuk example.conf.bak. Backup yang ditaruh di folder yang sama bisa membuat server block terbaca dua kali, lalu memunculkan warning duplikat atau error baru. Simpan backup di luar folder yang di-include, misalnya di home directory atau folder backup terpisah. Kalau server memakai panel kontrol yang menghasilkan config Nginx sendiri, edit manual di file hasil generate bisa tertimpa saat panel membangun ulang config. Cek dokumentasi panel tentang cara menambah config custom yang tidak ikut tertimpa.

Jadikan kebiasaan, bukan langkah darurat

Polanya cukup tiga langkah: sudo nginx -t, reload hanya kalau test lolos, lalu pastikan PID worker berganti dan situs merespons sesuai harapan lewat curl lokal. Kalau kamu memakai script deploy atau tool otomatisasi, pasang nginx -t sebagai syarat sebelum reload, supaya config rusak berhenti di tahap test dan tidak sampai ke service. Gunakan restart hanya kalau memang perlu, dan selalu setelah test lolos, karena restart yang gagal adalah satu-satunya skenario di sini yang langsung mematikan semua situs.