File Server #

Direktif file_server adalah modul inti yang bertanggung jawab di balik seluruh kemampuan Caddy untuk menyajikan berkas statis dari sistem penyimpanan lokal ke jaringan internet. Meskipun terlihat sederhana dari luar — sering kali hanya ditulis sebagai satu baris instruksi di Caddyfile — file_server sesungguhnya memiliki arsitektur internal yang sangat kaya, dilengkapi dengan berbagai fitur otomatisasi canggih seperti manajemen berkas terkompresi, negosiasi konten, penanganan berkas tersembunyi, hingga pemenuhan permintaan rentang data (range requests) untuk media streaming.

Artikel ini akan mengupas tuntas direktif file_server secara mendalam. Kita akan mempelajari bagaimana Caddy memproses permintaan masuk dalam pipa perutean internalnya, mengeksplorasi seluruh opsi konfigurasi tingkat lanjut, memahami cara kerja direktif pendukung seperti try_files untuk perutean fallback, mengoptimalkan pengiriman berkas melalui kompresi awal (precompressed assets), hingga memecahkan masalah umum (troubleshooting) yang sering ditemui di lingkungan produksi.

Alur Pipa Pemrosesan Permintaan file_server #

Ketika sebuah permintaan HTTP masuk ke server Caddy dan diteruskan ke direktif file_server, Caddy tidak sekadar langsung membaca file di disk. Caddy menjalankan serangkaian logika pemeriksaan terstruktur untuk memastikan keamanan dan efisiensi pengiriman data:

flowchart TD
    Step1["1. Resolusi Jalur Fisik:<br/>Gabungkan direktori dasar (root) dengan URI permintaan"] --> Step2{"2. Pemeriksaan File Tersembunyi (Hide List):<br/>Apakah file target ada di daftar 'hide'?"}
    
    Step2 -- "Ya" --> HideYes["Hentikan proses & Kembalikan HTTP 404 (atau 403)"]
    Step2 -- "Tidak" --> Step3{"3. Pemeriksaan Tipe Target (File vs Direktori):<br/>Apakah target berupa direktori?"}
    
    Step3 -- "Ya" --> DirYes{"Cari file indeks (misal: index.html). Jika ada, jadikan index.html sebagai target.<br/>Jika tidak ada index.html, periksa apakah opsi 'browse' aktif.<br/>Apakah 'browse' aktif?"}
    DirYes -- "Tidak" --> BrowseNo["Kembalikan HTTP 404"]
    DirYes -- "Ya" --> BrowseYes["Jadikan list index / file terpilih sebagai target"] --> Step4
    Step3 -- "Tidak" --> Step4{"4. Pemeriksaan Pra-Kompresi (Precompressed):<br/>Apakah opsi 'precompressed' aktif dan browser mengirimkan tajuk Accept-Encoding?"}
    
    Step4 -- "Ya" --> PreYes["Cek file.br atau file.gz di disk. Jika ada, kirim versi terkompresi langsung"] --> Step5
    Step4 -- "Tidak" --> Step5{"5. Evaluasi Conditional Request (ETag & Cache):<br/>Cek tajuk If-None-Match (ETag) atau If-Modified-Since dari browser.<br/>Apakah file berubah?"}
    
    Step5 -- "Tidak" --> CacheYes["Kembalikan HTTP 304 Not Modified (Tanpa Body)"]
    Step5 -- "Ya" --> CacheNo["Kembalikan HTTP 200 OK beserta isi berkas"]

Logika terstruktur di atas memastikan bahwa transfer data berjalan sehemat mungkin dan melindungi berkas-berkas sistem dari pemindaian tidak sah.

Semua Opsi Konfigurasi file_server #

Direktif file_server mendukung blok konfigurasi opsional untuk menyesuaikan perilakunya secara detail:

example.com {
    root * /var/www/html
    
    file_server {
        # 1. Menentukan nama-nama file indeks bawaan (urutan prioritas)
        index index.html index.htm default.html
        
        # 2. Mengaktifkan directory listing (default: nonaktif)
        # browse
        
        # 3. Menyembunyikan berkas/direktori dari akses publik
        # Mendukung glob pattern. Jalur relatif terhadap webroot.
        hide .git .env *.key secrets.json node_modules
        
        # 4. Menonaktifkan pengalihan trailing slash otomatis
        # disable_canonical_uris
        
        # 5. Menyajikan berkas terkompresi awal jika tersedia
        precompressed zstd br gzip
        
        # 6. Mengganti status kode respons (jarang digunakan)
        # status 403
    }
}

try_files vs Rewrite: Logika Perutean Fallback #

Direktif try_files adalah instruksi pembantu yang dieksekusi sebelum file_server. Tugas utamanya adalah memeriksa ketersediaan berkas di disk secara berurutan berdasarkan daftar jalur yang kita berikan, dan melakukan penulisan ulang (rewrite) jalur permintaan ke berkas pertama yang ditemukan.

Sintaks penulisan try_files:

try_files [jalur_uji_1] [jalur_uji_2] [jalur_fallback]

Mengapa Perilaku try_files Berbeda dari Rewrite Biasa? #

Penting bagi kita untuk memahami perbedaan model eksekusi antara try_files dan direktif rewrite standar:

  • rewrite (State Manipulation): Direktif rewrite langsung mengubah URI permintaan di dalam memori Caddy tanpa melakukan pengecekan apakah file target benar-benar ada di disk. Ini adalah manipulasi status (state) murni yang terjadi pada lapisan HTTP Caddy.
  • try_files (Filesystem Querying): Direktif try_files melakukan kueri I/O fisik ke sistem penyimpanan (filesystem query) untuk setiap argumen yang diuji. Jika berkas pertama ditemukan, proses penulisan ulang dihentikan. Hal ini sangat efisien karena mencegah terjadinya kesalahan perutean internal sebelum data diteruskan ke file_server.

Kasus Penggunaan: Tautan Bersih (Clean URLs tanpa .html) #

Kita ingin pengguna dapat mengakses halaman https://site.com/about tanpa perlu menuliskan ekstensi .html di akhir alamat, namun server tetap menyajikan berkas /about.html secara internal:

example.com {
    root * /var/www/html
    
    # Mencoba dalam urutan:
    # 1. Apakah ada file persis seperti yang diminta? ({path})
    # 2. Apakah ada file dengan ditambahkan .html? ({path}.html)
    # 3. Jika tidak ada, alihkan ke halaman error 404 kustom (/404.html)
    try_files {path} {path}.html /404.html
    
    file_server
}

Kasus Penggunaan: Fallback Aplikasi Halaman Tunggal (SPA) #

Pada aplikasi SPA, seluruh rute virtual harus diarahkan ke berkas indeks utama index.html:

app.example.com {
    root * /var/www/app/dist
    
    # Coba cari berkas fisik, jika tidak ada, arahkan ke /index.html
    try_files {path} /index.html
    
    file_server
}

Menyajikan Berkas Terkompresi Awal (Precompressed Assets) #

Menyajikan berkas statis berukuran besar seperti JavaScript (bundle) atau CSS yang tidak dikompresi adalah pemborosan lebar pita (bandwidth) jaringan. Namun, melakukan kompresi secara dinamis (on-the-fly) menggunakan modul encode pada setiap permintaan akan membebani prosesor CPU server.

Solusi paling optimal untuk server skala produksi adalah menggunakan fitur Precompressed Assets pada file_server:

example.com {
    root * /var/www/html
    
    file_server {
        # Caddy akan mendeteksi tajuk Accept-Encoding dari browser.
        # Jika browser mendukung Brotli ("br") dan file.js.br ada di disk,
        # Caddy langsung menyajikan file.js.br.
        precompressed zstd br gzip
    }
}

Integrasi dengan Bundler Modern (Vite / Webpack) #

Kita dapat mengonfigurasi bundler JavaScript modern kita untuk menghasilkan aset terkompresi secara otomatis saat proses kompilasi.

Contoh Konfigurasi Vite (vite.config.js): #

Menggunakan plugin vite-plugin-compression untuk kompresi Brotli dan Gzip otomatis:

import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import compression from 'vite-plugin-compression';

export default defineConfig({
  plugins: [
    react(),
    // Kompresi Gzip standar
    compression({ algorithm: 'gzip', ext: '.gz' }),
    // Kompresi Brotli untuk browser modern
    compression({ algorithm: 'brotliCompress', ext: '.br' })
  ]
});

Penanganan Trail Slash Kanonikal (Canonical URIs) #

Untuk menjaga konsistensi perutean dan mencegah masalah konten duplikat pada mesin pencari (SEO duplicate content penalty), file_server Caddy secara bawaan memaksa penulisan URI yang kanonikal:

Pola Pengalihan Kanonikal Caddy:

1. Target adalah DIREKTORI:
   Browser mengakses: /about (tanpa trailing slash)
   Logika Caddy: Menemukan bahwa "about" adalah folder di disk.
   Respons Caddy: HTTP 301 Redirect ke /about/ (dengan trailing slash).

2. Target adalah BERKAS:
   Browser mengakses: /style.css/ (dengan trailing slash)
   Logika Caddy: Menemukan bahwa "style.css" adalah file di disk.
   Respons Caddy: HTTP 301 Redirect ke /style.css (tanpa trailing slash).

Jika aplikasi web kita memerlukan integrasi dengan sistem warisan (legacy systems) yang tidak mendukung pengalihan trailing slash otomatis ini, kita dapat menonaktifkannya menggunakan opsi disable_canonical_uris:

example.com {
    root * /var/www/html
    
    file_server {
        # Mematikan pengalihan otomatis trailing slash
        disable_canonical_uris
    }
}

Serving dari Banyak Direktori Root (CDN Split Storage) #

Di lingkungan arsitektur aplikasi web yang kompleks, kita sering kali memisahkan penyimpanan berkas statis berdasarkan tipenya ke media penyimpanan atau mount-point disk yang berbeda. Sebagai contoh, berkas aset kode (.js dan .css) ditaruh di penyimpanan cepat SSD, sedangkan berkas unggahan pengguna (user uploads) ditaruh di penyimpanan besar HDD atau NFS (Network File System).

Caddy memfasilitasi kebutuhan ini dengan mengizinkan definisi beberapa direktif root yang terisolasi di bawah satu virtual host yang sama:

# Konfigurasi Split Storage CDN-like di Caddy
assets.example.com {
    # 1. Jalur gambar ditaruh di mount point HDD besar
    root /media/images/* /mnt/storage-hdd/images
    
    # 2. Jalur berkas video ditaruh di mount point video terpisah
    root /media/videos/* /mnt/storage-videos/videos
    
    # 3. Jalur kode statis ditaruh di SSD utama (/var/www/static)
    root /* /var/www/static
    
    # Kompresi dinamis khusus untuk aset kode
    encode {
        zstd
        gzip 6
    }
    
    # Handler file server global
    file_server {
        hide .git .env
    }
}

Range Requests (Pemutaran Media Streaming & Akses Parsial) #

Caddy secara out-of-the-box mendukung penuh spesifikasi HTTP Range Requests (status kode HTTP 206 Partial Content). Fitur ini sangat penting ketika server menyajikan berkas biner berukuran sangat besar:

  • Video/Audio Streaming: Browser dapat meminta potongan data video bagian tengah secara langsung saat pengguna menggeser linimasa pemutaran (scrubbing) tanpa perlu mengunduh seluruh file video dari awal.
  • Resume Downloads: Perkakas pengunduh (download manager) dapat melanjutkan proses unduhan yang terputus di tengah jalan tanpa perlu mengulang dari byte ke-0.

[!IMPORTANT] Jangan pernah mengaktifkan modul kompresi dinamis encode pada direktif yang menyajikan berkas video atau audio besar. Kompresi dinamis pada berkas media yang sudah terkompresi secara native (seperti MP4, WebM, MP3) tidak akan memperkecil ukuran file, melainkan justru akan merusak perhitungan offset byte pada Range Requests, sehingga fitur streaming dan resume download tidak akan berfungsi di browser pengguna.

ETag Kriptografis: Strong vs Weak ETag #

Caddy menggunakan penanda ETag untuk memfasilitasi conditional requests dari browser. Secara teknis, spesifikasi HTTP mendefinisikan dua jenis ETag:

  1. Strong ETag: Menjamin bahwa setiap byte berkas di server identik secara mutlak dengan berkas di cache browser. Diwakili dengan string hash langsung, misal "1a2b3c4d".
  2. Weak ETag (diawali prefiks W/): Menjamin bahwa konten secara semantik identik, namun mungkin ada perbedaan kecil pada tingkat byte (misal karena perbedaan metadata atau kompresi). Caddy secara default menghasilkan Weak ETag (misal W/"1a2b3c4d") karena pendekatan ini jauh lebih efisien untuk validasi aset web statis terkompresi.

Analisis Komparatif: Caddy vs Nginx untuk Berkas Statis #

Bagi administrator sistem yang terbiasa menggunakan Nginx, berikut adalah perbandingan baris konfigurasi yang setara untuk menyajikan static file lengkap dengan optimasi kompresi dan TLS otomatis:

Konfigurasi Nginx Tradisional: #

# /etc/nginx/sites-available/default
server {
    listen 80;
    listen 443 ssl http2;
    server_name example.com;

    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

    root /var/www/html;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
        gzip on;
        gzip_types text/css application/javascript text/html;
        gzip_min_length 1024;
        add_header X-Frame-Options SAMEORIGIN;
    }
}
# (Masih membutuhkan cronjob external certbot untuk SSL renewal)

Konfigurasi Caddyfile: #

# Setara penuh dengan konfigurasi Nginx di atas
example.com {
    root * /var/www/html
    try_files {path} /index.html
    encode gzip zstd
    header X-Frame-Options SAMEORIGIN
    file_server
}
# (SSL otomatis, perpanjangan otomatis, HTTP/3 diaktifkan otomatis)

Pemecahan Masalah (Troubleshooting) file_server #

1. HTTP 403 Forbidden #

  • Penyebab Utama: Hak akses direktori atau file di Linux tidak dapat dibaca oleh pengguna caddy.
  • Solusi: Jalankan sudo chown -R caddy:caddy /var/www/html dan pastikan direktori memiliki permission 755 agar dapat ditelusuri.

2. HTTP 404 Not Found (Padahal File Fisik Ada di Disk) #

  • Penyebab 1: Jalur yang dicari Caddy tidak sesuai akibat penggabungan root dan URI yang keliru (lihat bab Resolusi Jalur).
  • Solusi 1: Gunakan perintah caddy adapt untuk melihat bagaimana Caddy menerjemahkan Caddyfile menjadi konfigurasi JSON internal guna memverifikasi direktori root yang aktif.
  • Penyebab 2: File tersembunyi karena tidak sengaja ter-filter oleh opsi hide pada Caddyfile.
  • Solusi 2: Periksa kembali blok opsi hide di dalam direktif file_server kita.

Ringkasan #

  • Core Engine — Direktif file_server adalah tulang punggung penyajian berkas statis di Caddy yang menangani MIME Types, ETag, dan Range Requests secara otomatis.
  • Logika try_files — Digunakan untuk membuat fallback rute, memfasilitasi Tautan Bersih (Clean URLs), dan mendukung deployment SPA dengan mengalihkan rute virtual ke index.html.
  • Precompressed Assets — Menyajikan berkas terkompresi Brotli (.br), Gzip (.gz), atau Zstandard (.zst) secara langsung dari disk untuk menghemat CPU server.
  • Video Streaming — Range Requests (HTTP 206) aktif otomatis untuk video, namun pastikan tidak mengaktifkan modul encode pada file video agar offset byte tidak rusak.
  • MIME & ETag — Caddy otomatis mendeteksi tipe konten berkas dan menghasilkan tanda ETag dinamis untuk efisiensi transfer data browser menggunakan status kode 304.

← Sebelumnya: Virtual Host   Berikutnya: Directory Browse →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact