Belajar Caddy - Static File Serving

#Pendahuluan

Menyajikan file statis adalah tugas paling dasar sebuah web server — dan Caddy melakukannya dengan sangat baik. Di episode 5 ini, kalian akan belajar directive file_server dan root secara mendalam, ditambah fitur lanjutan seperti directory browsing, precompressed files, dan try_files untuk aplikasi Single Page Application.

File statis adalah fondasi banyak situs: HTML, CSS, JavaScript, gambar, dan dokumen download. Sekalipun kalian fokus ke reverse proxy, episode ini tetap penting — hampir semua situs membutuhkan setidaknya favicon, robots.txt, atau aset statis.

Setelah episode ini, kalian bisa membangun static site, dokumentasi, atau portfolio yang siap production dengan konfigurasi Caddyfile yang singkat.

#Directive file_server

#Penggunaan Dasar

Directive file_server melayani file dari document root. Paling sederhana:

example.com {
    root * /var/www/mysite
    file_server
}

Default index files adalah index.html (diikuti index.txt, dan lainnya). Jadi request ke / akan mengembalikan /var/www/mysite/index.html jika ada.

#Directory Browsing dan Index Files

Jika kalian ingin pengunjung bisa menjelajahi direktori:

files.example.com {
    root * /srv/downloads
    file_server browse
}

Dengan keyword browse, Caddy menampilkan daftar file ketika tidak ada index file. Untuk mengontrol nama file index:

example.com {
    root * /var/www
    file_server {
        index index.html home.html
    }
}

Blok file_server di atas menyatakan: cari index.html dulu, lalu home.html sebagai fallback. Ini berguna untuk halaman entry yang tidak standar.

#File Tersembunyi

Secara default, Caddy menolak melayani file yang dimulai dengan titik seperti .env atau .git. Ini keputusan keamanan yang bijak. Jangan menonaktifkannya kecuali benar-benar paham risikonya.

#Advanced File Serving

#Precompressed Files

Caddy bisa melayani file yang sudah dikompresi sebelumnya (.gz, .br, .zst) jika ada di samping file asli:

example.com {
    encode zstd gzip
    root * /var/www
    file_server {
        precompressed br gzip
    }
}

Jika /var/www/style.css.br ada, Caddy otomatis mengirimkannya untuk browser yang mendukung Brotli — mengurangi beban CPU karena kompresi tidak dihitung ulang per request.

#Range Requests dan ETags

Caddy mendukung range requests (pelengkap untuk resume download video) dan ETags (validasi cache) secara default. Kalian tidak perlu konfigurasi tambahan. Cukup pastikan file_server aktif.

#Directive try_files

#Fallback ke File Lain

try_files memeriksa keberadaan file lalu memilih yang pertama ada:

example.com {
    root * /var/www
    try_files {path} {path}.html /index.html
    file_server
}

Artinya: coba file persis path, lalu versi dengan ekstensi .html, lalu jatuh ke /index.html. try_files {path} /index.html adalah pola paling umum untuk routing SPA.

#SPA Routing

Aplikasi React, Vue, dan Angular butuh semua route dikembalikan ke index.html agar router JavaScript yang menanganinya:

spa.example.com {
    root * /app/dist
    try_files {path} /index.html
    file_server
}

Dengan pola ini, request /dashboard yang file-nya tidak ada akan mengembalikan index.html, lalu router SPA menampilkan halaman yang benar. Ini pola yang dipakai di hampir semua deployment frontend modern.

#Directive root

#Mengatur Document Root

root menentukan direktori tempat file dicari:

example.com {
    root * /var/www/public
    root /api /var/www/api-docs
    file_server
}

Baris pertama root * /var/www/public berlaku untuk semua path; baris kedua menimpa root khusus path /api. Jadi dokumentasi API yang berada di direktori terpisah bisa dilayani tanpa memindah file.

#Dynamic Root dengan Variables

Document root bisa dinamis menggunakan placeholder request:

*.example.com {
    root * /var/www/sites/{host}
    file_server
}

Kombinasi root * /var/www/sites/{host} dengan placeholder {host} membuat setiap subdomain dilayani dari direktori yang berbeda — pola hemat untuk multi-tenant statis. Kita akan mendalami variables di episode 12.

#Use Case File Server

#Kapan Memakai Pola Ini

• Static website: HTML, CSS, JS dengan root dan file_server.
• Single Page Application: tambahkan try_files {path} /index.html.
• File downloads: aktifkan file_server browse.
• Documentation site: generate ke folder statis lalu layani dengan Caddy.
• Portfolio: konfigurasi dua baris sudah cukup.

#Penutup

Episode 5 membuat kalian menguasai file serving statis: file_server dengan opsi browse, index, dan precompressed; try_files untuk SPA routing dan fallback; serta root dengan dynamic variables untuk konfigurasi per lokasi atau per host.

Inti yang harus dibawa pulang:

• file_server + root adalah kombinasi inti untuk file statis.
• Keyword browse menampilkan directory listing.
• Precompressed files menghemat CPU untuk aset besar.
• try_files {path} /index.html adalah pola routing SPA standar.
• root bisa diatur per lokasi dan bersifat dinamis.
• File tersembunyi ditolak secara default demi keamanan.

Di episode 6 selanjutnya kita masuk ke reverse proxy basics — directive reverse_proxy, manipulasi header dengan header_up dan header_down, pola proxy ke localhost dan container, WebSocket dan gRPC proxying, serta transport options seperti h2c dan timeouts. Ini pintu masuk ke dunia aplikasi dinamis.