Belajar Caddy - Architecture & Core Concepts

#Pendahuluan

Sekarang kalian sudah tahu mengapa Caddy ada. Episode 2 membawa kalian satu tingkat lebih dalam: memahami arsitektur dan core concepts yang menjadi dasar semua konfigurasi. Kalau kalian paham bahwa directive adalah aksi dan matcher adalah kriteria, maka membaca Caddyfile orang lain akan terasa seperti membaca bahasa yang sudah dikenal.

Caddy dibangun sebagai kumpulan modul yang berjalan di atas sebuah inti kecil. Arsitektur ini membuat Caddy mudah diperluas — hampir semua fitur, dari TLS sampai reverse proxy, adalah modul yang bisa diganti atau ditambah. Pemahaman ini juga yang membuat kalian bisa memakai fitur caddy list-modules dengan percaya diri.

Episode 2 mencakup komponen arsitektur, struktur Caddyfile, alur request, dan keempat metode konfigurasi yang tersedia. Tidak perlu menghafal semua istilah — yang penting kalian paham pola pikirnya.

#Komponen Arsitektur Caddy

#Inti Server dan Sistem Modul

Arsitektur Caddy terdiri dari beberapa lapisan:

• HTTP server core: engine yang menerima koneksi dan mengeksekusi handler.
• TLS management: modul yang menangani sertifikat dan protokol ACME.
• Reverse proxy engine: modul untuk meneruskan request ke backend.
• Module system: kerangka yang membuat semua fitur menjadi modul yang bisa di-load.
• Admin API: endpoint HTTP lokal untuk mengubah konfigurasi saat runtime.
• Storage layer: tempat sertifikat dan data ACME disimpan.

Setiap modul memiliki tipe dan nama. Ketika kalian menjalankan caddy list-modules, daftar panjang itu adalah semua modul yang ter-compile di binary kalian.

#Storage Layer: Tempat Sertifikat Disimpan

Caddy menyimpan sertifikat dan kunci di dalam storage, secara default di $XDG_DATA_HOME/caddy pada Linux. Konsep storage ini penting karena:

• Storage menentukan di mana sertifikat ACME diletakkan.
• Bisa dipindah ke Redis, S3, atau sistem file jaringan untuk cluster.
• Satu storage yang sama bisa dipakai banyak instance Caddy tanpa konflik.

Kita akan membahas storage mendalam di episode 7 dan 10.

#Struktur Caddyfile

#Site Block, Directive, dan Global Options

Caddyfile tersusun dari global options di bagian atas dan site blocks di bawahnya. Sebuah site block dibuka dengan alamat situs dan di dalamnya berisi directive:

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

• Site address: example.com menentukan domain yang dilayani.
• Directive: root, encode, file_server adalah aksi yang dieksekusi berurutan.
• Global options: opsi seperti email dan admin ditulis di luar site block.

#Matcher, Named Matcher, dan Snippet

Directive bisa dibatasi dengan matcher — kriteria yang menentukan request mana yang diproses. Ada dua bentuk:

• Inline matcher: langsung ditulis setelah directive, misalnya @api { path /api/* } atau header Content-Type application/json.
• Named matcher: diberi nama dengan awalan @, lalu dipakai ulang di beberapa directive.

Snippet adalah blok bernama yang bisa disisipkan ke banyak situs — analog dengan macro atau include:

(common) {
    encode gzip zstd
    header {
        X-Frame-Options DENY
    }
}
 
site-a.example.com {
    import common
    root * /var/www/a
    file_server
}

Snippet ditandai dengan tanda kurung di nama, dan dipanggil memakai directive import. Ini membuat konfigurasi yang berulang tetap DRY.

#Alur Request di Caddy

#Dari Listener ke Respons

Saat sebuah request tiba, Caddy menjalankan alur yang terstruktur:

1. Request tiba di listener (port 80 atau 443).
2. TLS di-handle lebih dulu jika HTTPS.
3. Matcher dievaluasi untuk menentukan directive mana yang berlaku.
4. Handler dieksekusi berurutan sesuai urutan directive.
5. Jika reverse proxy dikonfigurasi, request diteruskan ke backend.
6. Respons dikirim kembali ke klien.

Urutan directive penting: misalnya redir harus ditulis sebelum file_server agar redirect menangkap request lebih dulu. Kita akan membahas urutan dan penempatan di episode 4 dan 13.

#Konsep: Address, Directive, Matcher, Handler, Modul

• Site address: kombinasi domain dan port, misalnya localhost:8080.
• Directive: cara menulis konfigurasi yang mudah dibaca manusia.
• Matcher: kriteria request, seperti path, method, atau header.
• Handler: objek yang benar-benar memproses request.
• Modul: unit extensibility yang membungkus handler, matcher, dan fitur lain.

Satu directive bisa memetakan ke satu atau lebih handler, dan satu handler bisa dipakai banyak directive.

#Metode Konfigurasi Caddy

#Empat Cara Mengonfigurasi

Caddy menerima konfigurasi lewat empat jalur:

• Caddyfile: format manusiawi yang diubah menjadi JSON oleh adapter.
• JSON: format native yang dipahami Caddy secara langsung.
• Admin API: endpoint :2019 untuk memuat dan mengubah konfigurasi saat runtime.
• Adapters: transformasi format lain, seperti menambahkan adapter kustom.

Perintah caddy adapt menunjukkan JSON hasil konversi Caddyfile:

caddy adapt --config Caddyfile

Dan JSON bisa dimuat langsung lewat admin API:

curl -X POST -H 'Content-Type: application/json' \
     -d @config.json http://localhost:2019/load

curl -X POST ... -d @config.json adalah cara memuat konfigurasi dinamis. Admin API ini akan kita bedah menyeluruh di episode 23.

#Penutup

Episode 2 memperkenalkan fondasi konseptual Caddy: arsitektur modular dengan HTTP core, TLS management, reverse proxy engine, admin API, dan storage layer; struktur Caddyfile dengan site block, directive, matcher, named matcher, dan snippet; alur request dari listener sampai respons; serta empat metode konfigurasi.

Inti yang harus dibawa pulang:

• Semua fitur Caddy adalah modul; inti hanya menyediakan kerangka.
• Caddyfile terdiri dari global options dan site blocks.
• Matcher membatasi directive, snippet membuat konfigurasi bisa dipakai ulang.
• Urutan directive menentukan hasil eksekusi.
• Konfigurasi bisa berupa Caddyfile, JSON, atau dimuat via admin API.
• Storage layer menyimpan sertifikat dan bisa dibagi antar instance.

Di episode 3 selanjutnya kita akan menginstall Caddy secara lengkap — dari package manager resmi, binary download, Docker, hingga build dari source — dan menjalankan first run untuk memastikan semuanya bekerja sebelum masuk ke materi Caddyfile.