Struktur Konfigurasi & Konteks — Belajar Nginx

Konfigurasi Berbentuk Pohon

Konfigurasi Nginx tersusun dari konteks bersarang. Setiap konteks membatasi direktif mana yang boleh muncul dan bagaimana nilainya diwariskan ke bawah.

main                          # tingkat paling luar
├── events { }                # penyetelan koneksi
└── http { }                  # seluruh lalu lintas HTTP
    ├── upstream { }          # kelompok server hulu
    └── server { }            # satu situs virtual
        └── location { }      # satu pola URI

user              www-data;                    # konteks main
worker_processes  auto;

events {
    worker_connections  1024;
}

http {
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout  65;

    server {
        listen       80;
        server_name  contoh.id;
        root         /var/www/contoh;

        location / {
            try_files $uri $uri/ =404;
        }
    }
}

Warisan Berjalan ke Bawah — Sampai Ditimpa

Direktif yang ditulis di http berlaku untuk semua server di dalamnya, dan direktif di server berlaku untuk semua location. Menuliskan direktif yang sama di tingkat lebih dalam akan menimpa nilai warisan, bukan menambahkannya.

🚫 add_header berhenti diwariskan begitu ditulis ulang

Ini jebakan paling terkenal di Nginx. Bila add_header ditulis di http lalu satu saja add_header ditulis di dalam sebuah location, maka seluruh header dari tingkat atas hilang untuk location tersebut — bukan digabung. Header keamanan diam-diam lenyap tepat di endpoint yang paling perlu.

http {
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    server {
        location /api/ {
            add_header X-Custom nilai;   # dua header di atas HILANG di sini
        }
    }
}

# Solusi 1 — ulangi seluruh header di konteks dalam
# Solusi 2 — pakai always dan letakkan semua di satu tingkat
# Solusi 3 — Nginx modern: gunakan modul headers-more

Urutan Pemilihan Location

Nginx tidak membaca blok location dari atas ke bawah begitu saja. Urutannya sudah ditentukan:

location = /tepat        { }   # 1. sama persis — menang mutlak, berhenti
location ^~ /awalan/     { }   # 2. awalan prioritas — berhenti bila cocok
location ~  /regex/      { }   # 3. regex peka huruf besar-kecil, urut tulisan
location ~* /regex/i     { }   # 3. regex abaikan huruf besar-kecil
location /   awalan      { }   # 4. awalan terpanjang — cadangan terakhir

Alurnya: Nginx mencari kecocokan tepat lebih dulu. Bila tidak ada, ia mencatat awalan terpanjang yang cocok, lalu mencoba semua regex berurutan sesuai penulisan dan memakai regex pertama yang cocok. Bila tidak ada regex yang cocok, barulah awalan terpanjang tadi dipakai.

⚠️ Regex mengalahkan awalan, berapa pun panjangnya

Blok location ~ \.php$ akan menang atas location /aplikasi/berkas/ untuk permintaan ke /aplikasi/berkas/data.php, meskipun awalannya jauh lebih spesifik. Bila sebuah awalan harus dilindungi dari regex, tandai dengan ^~ supaya pencarian berhenti begitu awalan itu cocok.

Slash di Akhir root dan alias

location /gambar/ {
    root /data;              # /gambar/logo.png → /data/gambar/logo.png
}                            # root MENAMBAHKAN URI ke path

location /gambar/ {
    alias /data/berkas/;     # /gambar/logo.png → /data/berkas/logo.png
}                            # alias MENGGANTI bagian location

💡 Aturan slash pada alias

Bila location diakhiri slash, alias juga harus diakhiri slash. Bila tidak, path yang terbentuk akan salah dan sulit dilacak karena tidak memunculkan kesalahan sintaks — hanya 404 yang membingungkan.