Nginx SSI Include Virtual: Panduan Konfigurasi & Contoh

Directiva include virtual pada modul Server Side Includes (SSI) Nginx digunakan untuk mengambil dan menyertakan output dari lokasi internal atau skrip eksternal (seperti CGI, FastCGI, atau proxy) di dalam dokumen HTML. Berbeda dengan include file yang hanya membaca file statis secara langsung dari sistem file disk, include virtual memproses URI melalui sistem routing Nginx, memungkinkan pemanggilan blok lokasi lain, skrip PHP, atau layanan mikro secara dinamis.

Untuk mengaktifkan fitur ini, Anda harus memastikan bahwa modul SSI sudah aktif pada konteks server atau location menggunakan direktif ssi on;. Tanpa pengaktifan ini, Nginx akan mengabaikan tag SSI dan merendernya sebagai komentar HTML biasa.

Sintaks Dasar Nginx SSI Include Virtual

Penulisan tag SSI di dalam file HTML menggunakan format komentar HTML khusus agar dapat dikenali dan diproses oleh mesin SSI Nginx sebelum dikirimkan ke peramban pengguna. Berikut adalah sintaks standar untuk menyertakan konten virtual:

<!--# include virtual="/path/to/virtual/resource" -->

Atribut virtual menerima argumen berupa URI internal yang kemudian akan dicocokkan dengan blok location yang ada di dalam berkas konfigurasi Nginx Anda.

Tabel Perbandingan: Include File vs Include Virtual

Contoh Konfigurasi Nginx untuk SSI Virtual

Agar direktif include virtual berfungsi dengan baik, Anda perlu menyiapkan konfigurasi server Nginx yang mengizinkan SSI serta mendefinisikan blok location yang dituju oleh URI tersebut. Berikut adalah contoh blok server Nginx yang lengkap:

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

    index index.html index.htm;

    # Mengaktifkan SSI pada server level
    ssi on;

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

    # Lokasi internal yang dipanggil via include virtual
    location /api/header {
        internal;
        # Bisa berupa proxy ke backend atau konten lokal
        proxy_pass http://127.0.0.1:3000/header;
    }
}

Perhatikan penggunaan direktif internal; pada blok location /api/header. Pengaturan ini memastikan bahwa endpoint tersebut tidak dapat diakses langsung oleh pengguna melalui peramban web eksternal, melainkan hanya bisa dipanggil melalui subrequest internal Nginx.

Langkah Penerapan di Sisi Klien (HTML)

Setelah konfigurasi server disiapkan dan Nginx telah dimuat ulang (reload), Anda dapat menyisipkan kode SSI ke dalam file HTML utama, misalnya pada berkas index.html:

<!DOCTYPE html>
<html>
<head>
    <title>Halaman Utama SSI</title>
</head>
<body>
    <!-- Memuat header secara dinamis melalui virtual URI -->
    <!--# include virtual="/api/header" -->
    
    <main>
        <h1>Selamat Datang di Situs Kami</h1>
        <p>Konten utama halaman ini dimuat secara statis.</p>
    </main>
</body>
</html>

Troubleshooting Masalah Umum SSI Nginx

Kendala yang sering terjadi saat mengonfigurasi fitur ini adalah konten tidak muncul atau hanya menampilkan komentar HTML mentah di browser. Hal ini biasanya disebabkan oleh beberapa faktor teknis:

• SSI Belum Aktif: Pastikan direktif ssi on; didefinisikan di dalam blok http, server, atau location yang relevan.
• Format Komentar Salah: Sintaks SSI wajib menggunakan spasi yang tepat di dalam tanda kurung siku, yaitu <!--# perintah atribut="nilai" -->. Kesalahan spasi akan membuat Nginx mengabaikannya.
• Kesalahan Subrequest: Jika menggunakan proxy_pass pada location yang dituju, pastikan backend server merespons dengan cepat dan tidak mengalami timeout.