Struktur Caddyfile #

Bagi banyak administrator server dan developer, mengonfigurasi web server tradisional seperti Apache HTTPD atau Nginx sering kali menjadi pengalaman yang melelahkan. Berkas konfigurasi yang panjang, sintaksis yang kaku, melimpahnya kode boilerplate (seperti konfigurasi SSL/TLS manual), serta risiko kesalahan kecil yang dapat meruntuhkan seluruh server adalah masalah klasik yang terus berulang.

Caddy hadir dengan solusi radikal melalui Caddyfile. Caddyfile dirancang dari awal untuk menjadi bahasa konfigurasi yang berpusat pada manusia (human-centric). Tujuan utamanya sederhana namun ambisius: memungkinkan kita menulis konfigurasi web server yang lengkap, aman, berperforma tinggi, dan otomatis menggunakan HTTPS hanya dalam beberapa baris kode yang dapat dipahami oleh siapa saja, bahkan oleh mereka yang baru pertama kali melihatnya. Namun, di balik kesederhanaan tersebut, Caddyfile memiliki aturan terstruktur dan cara kerja parser unik yang harus kita pahami agar kita dapat membangun konfigurasi yang kompleks secara andal tanpa mengalami error tak terduga.

Mengapa Caddyfile Begitu Ringkas? #

Sebelum kita membedah aturan sintaksisnya, kita perlu memahami filosofi di balik keringkasan Caddyfile. Di web server tradisional, kita harus mendefinisikan secara eksplisit setiap langkah operasional, mulai dari port yang harus didengar (listen), lokasi sertifikat SSL, enkripsi cipher yang diizinkan, hingga pengalihan (redirect) dari HTTP ke HTTPS.

Caddy mengambil pendekatan yang berbeda dengan menerapkan prinsip sensible defaults (nilai bawaan yang masuk akal). Caddy berasumsi bahwa jika kita memasukkan nama domain publik di Caddyfile, kita pasti menginginkan:

1. Server berjalan di port standar HTTPS (443) dan HTTP (80).
2. Sertifikat TLS diperoleh dan diperbarui secara otomatis dari Let’s Encrypt atau ZeroSSL.
3. Semua koneksi HTTP tidak aman dialihkan secara otomatis ke HTTPS.
4. Protokol modern seperti HTTP/2 dan HTTP/3 diaktifkan secara bawaan.

Karena Caddy mengotomatiskan hal-hal berulang tersebut di latar belakang, berkas Caddyfile kita terbebas dari ratusan baris boilerplate dan hanya fokus pada logika bisnis server kita, seperti direktori file statis atau alamat reverse proxy backend.

Elemen Dasar Caddyfile #

Struktur Caddyfile dibangun dari tiga elemen utama: Global Options Block, Site Block, dan Directives.

Untuk memvisualisasikan bagaimana elemen-elemen ini berinteraksi, mari kita perhatikan diagram alur kompilasi dan pemrosesan berikut:

flowchart TD
    CF["Caddyfile (Format Ramah Manusia)"] --> Parser["Parser Caddy (Tokenisasi & Sintaksis)"]
    Parser --> Validation{"Valid?"}
    Validation -- "Tidak (Syntax Error)" --> Error["Tampilkan Error & Hentikan Proses"]
    Validation -- "Ya" --> Adapt["Proses Adaptasi (caddy adapt)"]
    Adapt --> JSON["JSON Config (Format Native Engine)"]
    JSON --> Engine["Engine Utama Caddy"]
    Engine --> AdminAPI["Admin API (localhost:2019)"]
    Engine -. "Manajemen TLS Otomatis" .-> ACME["Otoritas Sertifikat (Let's Encrypt / ZeroSSL)"]

Secara struktural, tata letak fisik elemen-elemen tersebut di dalam berkas Caddyfile adalah sebagai berikut:

flowchart TD
    subgraph Caddyfile["Caddyfile"]
        direction TB
        
        Global["Global Options Block (Opsional)"]
        
        subgraph Sites["Site Blocks"]
            direction TB
            Site1["Site Block 1 (example.com)"]
            Site2["Site Block 2 (api.example.com)"]
        end
    end

    style Caddyfile stroke:#333,stroke-width:2px
    style Global stroke:#0288d1,stroke-width:1px
    style Sites stroke:#757575,stroke-width:1px,stroke-dasharray:5,5

Berikut adalah ilustrasi kode Caddyfile berdasarkan struktur di atas:

# Global Options Block (Opsional)
{
    email [email protected]
}

# Site Block 1
example.com {
    directive1 arg1 arg2
    directive2 {
        subdirective key value
    }
}

# Site Block 2
api.example.com {
    directive3
}

1. Global Options Block (Blok Opsi Global) #

Blok ini ditulis di bagian paling atas berkas Caddyfile dan dibungkus dengan kurung kurawal { } tanpa menyertakan alamat situs (site address) sebelumnya. Blok ini bersifat opsional namun sangat penting untuk mengontrol perilaku seluruh instansi server Caddy, seperti alamat email untuk pendaftaran sertifikat SSL otomatis, tingkat detail log global (debug mode), port default, dan setelan proxy tepercaya.

2. Site Block (Blok Situs) #

Blok situs mendefinisikan bagaimana Caddy harus menangani permintaan untuk alamat tertentu. Blok situs dimulai dengan satu atau beberapa alamat situs (site address), diikuti oleh kurung kurawal pembuka {, daftar instruksi (directives), dan diakhiri dengan kurung kurawal penutup }.

Jika berkas Caddyfile kita hanya berisi konfigurasi untuk satu situs saja, kurung kurawal pembuka dan penutup blok situs dapat ditiadakan. Caddy akan menganggap seluruh isi berkas tersebut berada di dalam satu blok situs implisit. Namun, jika kita memiliki lebih dari satu blok situs, kurung kurawal pembungkus untuk setiap blok situs menjadi wajib ditulis secara eksplisit.

3. Directives (Arahan/Instruksi) #

Directives adalah instruksi blok fungsional yang kita letakkan di dalam blok situs. Setiap directive memberi tahu Caddy untuk melakukan tindakan spesifik pada lalu lintas data yang masuk. Contohnya adalah root (menentukan folder root file), file_server (mengaktifkan layanan berkas statis), dan reverse_proxy (meneruskan permintaan ke server aplikasi backend).

Directives dapat memiliki argumen opsional yang ditulis di baris yang sama, atau memiliki blok konfigurasi sendiri (subdirectives) yang dibungkus dengan kurung kurawal untuk kustomisasi lebih lanjut.

Token dan Cara Caddy Membaca Caddyfile #

Di balik layar, parser Caddy membaca berkas Caddyfile dengan memecahnya menjadi serangkaian token. Tokenisasi ini sangat mirip dengan cara shell sistem operasi (seperti bash atau zsh) membaca perintah baris terminal. Parser menggunakan spasi (whitespace) dan baris baru (newline) sebagai pemisah antar-token.

Aturan Quoting (Tanda Kutip) #

Karena parser memecah teks berdasarkan spasi, argumen apa pun yang secara natural mengandung spasi wajib dibungkus dengan tanda kutip ganda ("..."). Jika kita tidak membungkus nilai tersebut dengan kutip ganda, parser akan membacanya sebagai beberapa argumen terpisah, yang dapat menyebabkan kegagalan pembacaan konfigurasi (syntax error).

Asalkan contoh, perhatikan perbedaan penulisan berikut:

# ANTI-PATTERN: Menulis nilai yang memiliki spasi tanpa pembungkus tanda kutip
# Caddy akan membaca ini sebagai directive 'root' dengan argumen '*', '/var/www/my', dan 'awesome', lalu 'website' yang memicu error
root * /var/www/my awesome website

# BENAR: Membungkus nilai yang mengandung spasi dengan tanda kutip ganda
root * "/var/www/my awesome website"

Tanda kutip juga dapat digunakan untuk memasukkan karakter khusus atau baris kosong di dalam argumen tertentu. Jika nilai argumen mengandung tanda kutip ganda itu sendiri, kita dapat melakukan escaping menggunakan karakter backslash (\").

Semantik Baris Baru (Newline) #

Dalam bahasa pemrograman seperti JavaScript atau C++, titik koma (;) digunakan untuk mengakhiri pernyataan, sementara baris baru umumnya diabaikan oleh parser. Caddyfile menerapkan aturan sebaliknya. Baris baru memiliki makna semantik yang sangat penting: baris baru menandai akhir dari satu instruksi (directive).

Kita tidak boleh menulis lebih dari satu directive di dalam satu baris yang sama. Perhatikan contoh berikut:

# ANTI-PATTERN: Menulis beberapa directive dalam satu baris untuk menghemat ruang
# Caddy akan menganggap 'file_server' sebagai argumen dari 'root' dan memicu kegagalan startup
root * /var/www/html file_server

# BENAR: Pisahkan setiap directive dengan baris baru
root * /var/www/html
file_server

Jika kita memiliki argumen yang sangat panjang dan ingin membaginya ke dalam beberapa baris agar lebih mudah dibaca manusia, kita dapat menggunakan karakter backslash (\) di akhir baris sebagai tanda pelanjutan (line continuation). Namun, dalam skenario dunia nyata, teknik ini sangat jarang diperlukan karena struktur Caddyfile yang sudah ringkas.

Aturan Kurung Kurawal (Braces) #

Parser Caddyfile sangat ketat mengenai penempatan tanda kurung kurawal pembuka {. Kurung kurawal pembuka wajib diletakkan di baris yang sama dengan alamat situs atau nama directive. Penempatan kurung kurawal pembuka di baris baru akan memicu kegagalan analisis sintaksis.

Mengapa demikian? Karena jika parser menemukan nama situs atau directive, lalu mendeteksi baris baru di ujungnya, parser akan menganggap instruksi tersebut telah selesai. Ketika parser menemukan kurung kurawal pembuka { di baris berikutnya, parser akan bingung dan menganggap { sebagai alamat situs baru yang tidak valid.

# ANTI-PATTERN: Menempatkan kurung kurawal pembuka di baris baru
# Caddy akan membaca 'example.com' sebagai situs satu baris kosong, lalu menganggap '{' sebagai nama domain baru yang salah
example.com
{
    reverse_proxy localhost:3000
}

# BENAR: Kurung kurawal pembuka harus berada di baris yang sama
example.com {
    reverse_proxy localhost:3000
}

Komentar dalam Caddyfile #

Komentar sangat penting untuk menjelaskan maksud konfigurasi kita kepada rekan tim atau diri kita sendiri di masa depan. Caddyfile menggunakan karakter tag pagar (#) untuk mendefinisikan komentar.

Setiap teks yang ditulis setelah karakter # hingga akhir baris akan diabaikan sepenuhnya oleh parser Caddy. Perlu dicatat bahwa Caddyfile tidak mendukung komentar multiline (seperti /* ... */ di bahasa pemrograman). Jika kita ingin menulis komentar panjang yang terdiri dari beberapa baris, kita harus memulai setiap baris tersebut dengan karakter # secara individual.

# ==========================================
# KONFIGURASI PROXY UNTUK SERVER APLIKASI
# ==========================================
# Snippet ini memastikan semua koneksi websocket
# diteruskan dengan timeout yang memadai.
example.com {
    # Komentar inline di dalam blok situs juga diperbolehkan
    root * /var/www/html
    reverse_proxy localhost:8080 # Proxy ke backend Go/Node.js
}

Mengelola Banyak Situs dan Alamat #

Salah satu kekuatan utama Caddy adalah kemampuannya untuk mengelola puluhan hingga ratusan situs web independen hanya dalam satu berkas Caddyfile yang sama. Setiap situs dapat memiliki perilaku, domain, dan port yang sepenuhnya berbeda.

Satu Blok untuk Banyak Domain #

Sering kali, kita ingin beberapa domain memiliki konfigurasi yang identik. Misalnya, kita ingin domain utama example.com dan subdomain www.example.com dilayani oleh direktori file statis yang sama. Caddyfile memungkinkan kita menetapkan beberapa alamat situs ke satu blok situs yang sama menggunakan pemisah koma (,) atau baris baru.

# Opsi 1: Memisahkan alamat domain menggunakan koma dalam satu baris
example.com, www.example.com, blog.example.com {
    root * /var/www/main
    file_server
}

# Opsi 2: Menuliskan setiap domain di baris baru (Sangat direkomendasikan untuk keterbacaan)
example.com
www.example.com
blog.example.com {
    root * /var/www/main
    file_server
}

Kedua metode di atas menghasilkan konfigurasi internal yang sama persis di dalam engine Caddy. Namun, opsi kedua lebih disukai karena memudahkan kita dalam membaca dan melakukan pelacakan perubahan (git diff) jika di kemudian hari ada domain yang ditambahkan atau dihapus.

Urutan Eksekusi Directive (Direktif) #

Ini adalah konsep yang paling sering membingungkan pengguna baru Caddy: Urutan penulisan directive di dalam Caddyfile secara default tidak menentukan urutan penanganan request oleh server.

Di web server seperti Nginx, urutan baris kode konfigurasi sering kali sangat menentukan bagaimana permintaan diproses. Jika kita salah meletakkan baris pengalihan (rewrite) di bawah reverse proxy, pengalihan tersebut mungkin tidak pernah dieksekusi. Caddy menyelesaikan masalah ini dengan mendefinisikan urutan prioritas internal untuk semua directive bawaannya.

Artinya, meskipun kita menulis file_server di baris pertama dan root di baris terakhir blok situs kita, Caddy secara cerdas akan mengeksekusi root terlebih dahulu untuk menetapkan direktori kerja, baru kemudian mengeksekusi file_server untuk melayani berkas dari direktori tersebut.

Berikut adalah tabel urutan prioritas eksekusi handler internal Caddy, diurutkan dari yang dieksekusi paling awal hingga paling akhir:

Mengubah Urutan Default: Blok route #

Dalam sebagian besar skenario, urutan prioritas default di atas sudah sangat optimal dan aman. Namun, ada kalanya kita memiliki kebutuhan khusus untuk melompati atau mengubah urutan tersebut. Caddy menyediakan blok khusus bernama route untuk tujuan ini.

Di dalam blok route, urutan penulisan kode kembali bersifat linier. Caddy akan mengeksekusi directives di dalam blok route tepat sesuai urutan baris penulisannya di Caddyfile.

# Mengapa kita butuh blok route?
# Secara default, Caddy akan mengeksekusi 'basicauth' (urutan 8) SEBELUM 'reverse_proxy' (urutan 18).
# Namun, jika kita ingin memotong jalur request ke admin area secara kondisional:
example.com {
    route {
        # Kita ingin memvalidasi parameter tertentu, lalu melakukan penulisan ulang URI
        # sebelum autentikasi diperiksa
        rewrite /admin-internal/* /login-bypass
        
        # Eksekusi request berikutnya
        reverse_proxy localhost:8080
    }
}

Selain route, ada juga blok handle yang mirip namun dengan sifat eksklusivitas mutual (hanya satu blok handle yang cocok yang akan dieksekusi). Konsep handle ini dibahas secara lebih mendalam pada artikel Request Matcher.

Variabel Environment dan Placeholder #

Agar Caddyfile kita fleksibel dan aman untuk digunakan di berbagai lingkungan kerja (seperti Development, Staging, dan Production), Caddy mendukung penggunaan variabel dinamis.

1. Variabel Environment (Lingkungan) #

Kita dapat menyisipkan variabel lingkungan sistem operasi langsung ke dalam Caddyfile menggunakan sintaksis {env.NAMA_VARIABEL}. Ini adalah praktik terbaik (best practice) untuk menyembunyikan informasi sensitif seperti token API DNS, kunci enkripsi, atau port backend agar tidak tertulis secara keras (hardcoded) di dalam Caddyfile.

# Membaca konfigurasi domain dan port backend dari environment variable
{env.SITE_DOMAIN} {
    reverse_proxy localhost:{env.BACKEND_PORT}
    
    tls {
        dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    }
}

Sebelum kita menjalankan Caddy, kita cukup mendefinisikan variabel-variabel tersebut di sistem operasi kita:

export SITE_DOMAIN="myplatform.com"
export BACKEND_PORT="9000"
export CLOUDFLARE_API_TOKEN="cf_secure_token_abc123"

# Jalankan Caddy
caddy run --config Caddyfile

2. Placeholder Runtime #

Berbeda dengan variabel lingkungan yang nilainya ditentukan saat Caddy pertama kali dijalankan, placeholder adalah variabel internal Caddy yang nilainya dievaluasi pada saat request diproses (runtime). Sintaksis placeholder ditulis dengan tanda kurung kurawal {nama.placeholder}.

Beberapa placeholder yang sangat sering digunakan meliputi:

• {http.request.host} — Domain yang diminta oleh client.
• {http.request.uri} — Jalur URI lengkap beserta query string (misal: /users?id=10).
• {http.request.orig_uri.path} — Jalur path asli sebelum dimodifikasi oleh directive rewrite.
• {http.request.remote.ip} — Alamat IP asli milik client yang mengirimkan request.
• {http.request.header.User-Agent} — Informasi browser/client yang digunakan.

Contoh implementasi placeholder untuk melakukan pengalihan domain dinamis:

www.example.com {
    # Mengalihkan seluruh request ke domain apex dengan mempertahankan path asli yang diminta client
    redir https://example.com{http.request.uri} permanent
}

Peralatan CLI untuk Caddyfile #

Caddy menyediakan beberapa perintah baris (CLI tools) bawaan yang sangat membantu kita dalam mengelola, memformat, dan memvalidasi berkas Caddyfile.

1. Memvalidasi Sintaksis (caddy validate) #

Sebelum kita melakukan perubahan konfigurasi di server produksi yang sedang berjalan, kita harus selalu memverifikasi apakah sintaksis berkas Caddyfile kita sudah benar dan bebas dari kesalahan tulis. Perintah caddy validate akan memeriksa berkas tanpa menjalankan server.

caddy validate --config /etc/caddy/Caddyfile

Jika konfigurasi valid, Caddy akan menampilkan pesan sukses. Jika tidak, Caddy akan menunjukkan baris mana yang mengalami error beserta alasannya secara spesifik.

2. Memformat Berkas Konfigurasi (caddy fmt) #

Konsistensi gaya penulisan kode di dalam tim sangat penting untuk meminimalkan konflik saat melakukan penggabungan kode (code review). Caddy memiliki formatter otomatis bawaan yang dapat merapikan Caddyfile kita sesuai standar resmi Caddy.

Secara default, formatter Caddy menggunakan karakter tab untuk indentasi (bukan spasi).

# Menampilkan hasil format di terminal tanpa mengubah berkas asli
caddy fmt /etc/caddy/Caddyfile

# Langsung memperbarui berkas asli dengan hasil format yang rapi
caddy fmt --overwrite /etc/caddy/Caddyfile

3. Mengadaptasi Caddyfile ke JSON (caddy adapt) #

Engine inti Caddy sebenarnya tidak memahami sintaksis Caddyfile secara langsung. Engine Caddy berkomunikasi secara internal menggunakan struktur konfigurasi berformat JSON. Caddyfile hanyalah lapisan abstraksi (syntactic sugar) tingkat tinggi yang dirancang untuk mempermudah hidup kita sebagai administrator server.

Kita dapat menggunakan perintah caddy adapt untuk melihat bagaimana Caddy menerjemahkan baris-baris Caddyfile kita menjadi struktur JSON native. Perangkat ini sangat berguna untuk memecahkan masalah konfigurasi yang rumit (debugging).

caddy adapt --config /etc/caddy/Caddyfile --adapter caddyfile

Hubungan Caddyfile dan JSON Native #

Mari kita lakukan eksperimen kecil untuk memahami bagaimana Caddy menerjemahkan abstraksi Caddyfile menjadi JSON yang dipahami oleh engine utama. Misalkan kita memiliki Caddyfile sederhana berikut:

example.com {
    reverse_proxy localhost:3000
}

Saat kita menjalankan perintah caddy adapt, parser Caddy akan menghasilkan output JSON terstruktur yang mirip dengan ini (disederhanakan untuk kejelasan):

{
  "apps": {
    "http": {
      "servers": {
        "srv0": {
          "listen": [
            ":443",
            ":80"
          ],
          "routes": [
            {
              "match": [
                {
                  "host": [
                    "example.com"
                  ]
                }
              ],
              "handle": [
                {
                  "handler": "subroute",
                  "routes": [
                    {
                      "handle": [
                        {
                          "handler": "reverse_proxy",
                          "upstreams": [
                            {
                              "dial": "localhost:3000"
                            }
                          ]
                        }
                      ]
                    }
                  ]
                }
              ],
              "terminal": true
            }
          ]
        }
      }
    },
    "tls": {
      "automation": {
        "policies": [
          {
            "subjects": [
              "example.com"
            ]
          }
        ]
      }
    }
  }
}

Dari hasil adaptasi JSON di atas, kita dapat mengamati beberapa proses otomatis yang dilakukan oleh Caddy:

1. Meskipun kita hanya menulis nama domain example.com, parser otomatis mendefinisikan array listen pada port :443 (HTTPS) dan port :80 (untuk pengalihan HTTP ke HTTPS otomatis).
2. Kebijakan otomatisasi TLS (tls.automation.policies) dikonfigurasi untuk subjek example.com, yang memicu pengambilan sertifikat SSL otomatis.
3. Direktif reverse_proxy diubah menjadi objek handler terstruktur dengan target dial ke alamat localhost:3000.

Ini membuktikan bahwa Caddyfile berhasil menghemat waktu kita dari menulis puluhan baris konfigurasi JSON yang rumit dan rentan salah ketik.

Anti-Pattern Umum dan Solusi #

Berikut adalah rangkuman kesalahan sintaksis struktur yang paling sering dijumpai beserta solusi perbaikannya:

# ====================================================================
# ANTI-PATTERN 1: Lupa menuliskan kurung kurawal penutup
# ====================================================================
# JANGAN: Lupa menutup blok situs
example.com {
    root * /var/www/html
    file_server
# ← Error! Caddy akan mendeteksi EOF (End Of File) tanpa penutup yang sesuai

# BENAR: Selalu pastikan kurung kurawal berpasangan dengan benar
example.com {
    root * /var/www/html
    file_server
}

# ====================================================================
# ANTI-PATTERN 2: Kurung kurawal pembuka di baris baru
# ====================================================================
# JANGAN: Menulis kurung kurawal pembuka setelah baris baru
example.com
{
    file_server
}

# BENAR: Letakkan di baris yang sama dengan domain
example.com {
    file_server
}

# ====================================================================
# ANTI-PATTERN 3: Menumpuk beberapa blok situs tanpa pemisah yang jelas
# ====================================================================
# JANGAN: Menulis alamat situs berikutnya tepat di bawah instruksi situs sebelumnya
# tanpa kurung kurawal yang menutup blok sebelumnya terlebih dahulu
example1.com {
    reverse_proxy localhost:3000
    
example2.com {
    reverse_proxy localhost:4000
}

# BENAR: Tutup blok situs pertama sebelum mendeklarasikan situs kedua
example1.com {
    reverse_proxy localhost:3000
}

example2.com {
    reverse_proxy localhost:4000
}

Ringkasan #

• Blok Opsi Global ditulis tanpa alamat situs di bagian paling atas berkas Caddyfile dan dibungkus dengan kurung kurawal {}.
• Kurung Kurawal Pembuka ({) wajib diletakkan di baris yang sama dengan nama situs atau directive pembuka; meletakkannya di baris baru akan memicu syntax error.
• Semantik Spasi & Tanda Kutip sangat ketat karena parser Caddy memecah instruksi berdasarkan spasi. Nilai argumen yang mengandung spasi wajib dibungkus dengan tanda kutip ganda ("...").
• Urutan Penulisan Directive di Caddyfile tidak memengaruhi urutan eksekusi internal Caddy. Gunakan blok route jika kita ingin mengeksekusi instruksi secara linier sesuai urutan baris.
• Variabel Lingkungan ({env.NAMA_VAR}) dan Placeholder ({http.request.uri}) membantu kita membuat konfigurasi yang dinamis dan aman.
• Gunakan perintah caddy validate untuk memverifikasi sintaks, caddy fmt untuk merapikan berkas secara otomatis, dan caddy adapt untuk melihat terjemahan JSON aslinya.

← Sebelumnya: Compile dari Source   Berikutnya: Site Address →