Directive #

Directive (arahan/instruksi) adalah elemen pembangun utama di dalam blok situs Caddyfile. Jika alamat situs (site address) memberi tahu Caddy di mana ia harus mendengarkan permintaan, maka directives memberi tahu Caddy apa yang harus dilakukan terhadap permintaan tersebut.

Tanpa directives, Caddy hanyalah sebuah server kosong yang tidak melakukan apa-apa. Dengan menggunakan satu atau beberapa directive, kita dapat mengubah Caddy menjadi server file statis yang sangat cepat, reverse proxy tangguh di depan kluster aplikasi kita, server PHP dengan integrasi FastCGI, atau gerbang keamanan berlapis yang menyaring akses menggunakan autentikasi. Memahami cara kerja, anatomi penulisan, dan opsi konfigurasi dari masing-masing directive utama adalah keterampilan paling krusial untuk menguasai Caddy di lingkungan produksi.

Urutan Pemrosesan Request via Directive #

Ketika sebuah request HTTP masuk, Caddy akan memproses request tersebut melalui serangkaian directives yang aktif. Urutan pemrosesan ini mengikuti aturan prioritas internal Caddy.

Untuk memvisualisasikan bagaimana request dari client mengalir melalui berbagai directive hingga diteruskan ke backend dan dikembalikan sebagai response, mari perhatikan diagram urutan (sequence diagram) berikut:

sequenceDiagram
    autonumber
    participant Client as "Client (Browser)"
    participant Caddy as "Caddy Web Server"
    participant Backend as "Upstream App (Port 3000)"

    Client->>Caddy: "GET /admin/users (HTTP Request)"
    note over Caddy: 1. Evaluasi Matcher & Urutan Directive
    note over Caddy: 2. root /var/www (Tetapkan direktori)
    note over Caddy: 3. rewrite (Modifikasi URI internal jika ada)
    Caddy->>Client: "4. basicauth (Kirim Tantangan 401 jika Belum Otentikasi)"
    Client->>Caddy: "GET /admin/users (Kirim credentials)"
    note over Caddy: 5. basicauth (Validasi Hash Bcrypt Berhasil)
    note over Caddy: 6. encode (Siapkan filter gzip/zstd)
    Caddy->>Backend: "7. reverse_proxy (Kirim request dengan Header Diperbarui)"
    Backend-->>Caddy: "8. Response (Kirim HTML/JSON)"
    note over Caddy: 9. header (Tambahkan Security Headers & Hapus header Server)
    note over Caddy: 10. Kompresi respon via encode (gzip/zstd)
    Caddy-->>Client: "11. Response (Kirim ke Client dengan TLS Aktif)"

Anatomi Penulisan Directive #

Caddyfile dirancang agar sangat fleksibel. Directive dapat ditulis dalam tiga format sesuai dengan kompleksitas konfigurasi yang kita butuhkan:

1. Format Inline (Satu Baris) #

Digunakan untuk instruksi sederhana yang tidak membutuhkan banyak parameter atau konfigurasi tambahan.

example.com {
    # Format: nama_directive [argumen...]
    root * /var/www/html
    file_server
    encode gzip
}

2. Format Blok #

Digunakan jika directive memiliki banyak parameter kustom (subdirectives) yang perlu diatur secara detail agar lebih terstruktur dan mudah dibaca.

example.com {
    # Format:
    # nama_directive {
    #     subdirective1 argumen
    #     subdirective2 argumen
    # }
    log {
        output file /var/log/caddy/access.log
        format json
        level INFO
    }
}

3. Format Campuran (Inline & Blok) #

Banyak directive di Caddy mendukung penulisan inline untuk kasus standar, namun juga menerima blok kurung kurawal jika kita ingin melakukan penyetelan tingkat lanjut.

example.com {
    # Inline: Cepat dan menggunakan setelan bawaan
    encode gzip zstd
    
    # Blok: Kustomisasi level kompresi dan ukuran minimum file
    encode {
        gzip 6
        zstd
        minimum_length 1024
    }
}

Penjelasan 10+ Directive Utama #

Berikut adalah pembahasan mendalam mengenai directives yang paling sering digunakan untuk membangun konfigurasi server di dunia nyata:

1. `root` (Menetapkan Folder Root) #

Menentukan jalur direktori kerja di mana Caddy akan mencari berkas-berkas statis untuk dilayani oleh file_server atau diolah oleh php_fastcgi.

# Format: root [matcher] path
root * /var/www/my-app

Argumen * adalah wildcard request matcher yang memberi tahu Caddy untuk menggunakan root folder ini untuk seluruh lalu lintas request.

2. `file_server` (Menyajikan Berkas Statis) #

Mengaktifkan kapabilitas Caddy sebagai web server statis berkinerja tinggi untuk melayani gambar, berkas HTML, CSS, JavaScript, atau dokumen lainnya dari disk lokal.

example.com {
    root * /var/www/static
    
    # Aktifkan layanan file server dengan opsi tambahan
    file_server {
        # Aktifkan tampilan daftar direktori jika file index tidak ditemukan
        browse
        
        # Sembunyikan file sensitif dari daftar direktori dan blokir akses langsung
        hide .git .env *.config
        
        # Urutan prioritas pencarian file indeks (default: index.html)
        index index.html index.htm
    }
}

3. `reverse_proxy` (Proxy ke Backend Aplikasi) #

Salah satu fitur terkuat Caddy untuk meneruskan request masuk ke satu atau beberapa server aplikasi backend (seperti Node.js, Go, Python, Java, atau Docker containers).

example.com {
    # Meneruskan request ke upstream backend
    reverse_proxy localhost:3000 {
        # Manipulasi header request sebelum dikirim ke backend
        header_up Host {upstream_hostport}
        header_up X-Real-IP {remote_host}
        header_up X-Forwarded-For {remote_host}
        header_up X-Forwarded-Proto {scheme}
        
        # Opsi Load Balancing (jika upstream lebih dari satu)
        # Caddy mendukung round_robin, random, ip_hash, dll.
        lb_policy round_robin
        
        # Health check untuk mendeteksi upstream yang mati
        health_uri /health-check
        health_interval 10s
        health_timeout 5s
        
        # Penyetelan timeout koneksi
        transport http {
            dial_timeout 5s
            response_header_timeout 30s
        }
    }
}

4. `encode` (Kompresi Konten) #

Mengurangi ukuran data response yang dikirimkan ke client untuk menghemat bandwidth server dan mempercepat pemuatan halaman web.

example.com {
    # Aktifkan gzip dan zstd (Caddy akan memilih yang terbaik berdasarkan browser user)
    encode gzip zstd {
        # Mengatur kualitas kompresi gzip (1-9, default: 4)
        gzip 5
        # Mengatur kualitas zstd
        zstd
        # Jangan kompres file yang ukurannya di bawah 512 byte (karena tidak efisien)
        minimum_length 512
    }
}

5. `header` (Manipulasi Header HTTP) #

Menambahkan, memodifikasi, atau menghapus header HTTP di dalam response yang dikirimkan ke browser pengguna. Ini adalah alat utama untuk menerapkan kebijakan keamanan (security headers).

example.com {
    header {
        # Menambahkan header baru (atau mengganti jika sudah ada)
        Strict-Transport-Security "max-age=31536000; includeSubDomains"
        X-Frame-Options "SAMEORIGIN"
        X-Content-Type-Options "nosniff"
        
        # Menghapus header bawaan Caddy/backend demi keamanan info server
        -Server
        -X-Powered-By
        
        # Menambahkan nilai baru ke header yang sudah ada tanpa menimpanya (append)
        +Cache-Control "public"
    }
}

6. `redir` (Pengalihan URL Eksternal) #

Mengirimkan status pengalihan HTTP (seperti 301 untuk permanen atau 302 untuk sementara) kembali ke browser client agar mereka mengakses URL baru.

# Mengalihkan lalu lintas secara permanen
redir /peta-situs /sitemap.xml permanent

# Mengalihkan dengan parameter query yang dipertahankan
redir /produk/* /barang-baru/{path} 308

7. `rewrite` (Penulisan Ulang URI Internal) #

Berbeda dengan redir, rewrite mengubah jalur URI request secara diam-diam di dalam engine Caddy tanpa memberi tahu browser client. Browser akan tetap melihat URL asli di kolom alamatnya.

example.com {
    # Jika user mengakses /bantuan, Caddy memprosesnya sebagai /support/faq.html di latar belakang
    rewrite /bantuan /support/faq.html
    
    # Cocok untuk mendukung arsitektur Single Page Application (SPA) seperti React/Vue/Angular
    # Jika file tidak ditemukan di disk, arahkan request secara internal ke index.html
    @notFile {
        not file {path}
        not path /api/*
    }
    rewrite @notFile /index.html
    
    file_server
}

Perbedaan Fundamental: `redir` vs `rewrite` #

redir (External Redirect): Caddy mengirimkan response HTTP 301/302/308 ke browser client. Browser kemudian melakukan koneksi ulang ke URL baru. Terjadi dua kali round-trip HTTP di jaringan. URL di browser berubah.
rewrite (Internal Redirect): Caddy langsung mengarahkan request ke handler lain secara internal. Hanya terjadi satu kali round-trip HTTP. URL di browser client tetap sama.

8. `respond` (Mengirimkan Response Langsung) #

Mengirimkan response teks biasa, HTML, atau JSON secara instan ke client tanpa perlu membaca berkas dari disk atau menghubungi server backend.

# Mengirim teks biasa dengan status code 200
respond "Server OK" 200

# Mengirim data JSON untuk endpoint kesehatan
@health path /health
respond @health `{"status":"healthy","database":"connected"}` 200 {
    close
}

9. `basicauth` (HTTP Basic Authentication) #

Mengamankan path situs menggunakan lapisan proteksi username dan password. Password wajib disimpan dalam format hash bcrypt.

example.com {
    # Batasi akses ke folder /admin/
    basicauth /admin/* {
        # Username: admin, Password: password123 (hash dibuat menggunakan perintah CLI Caddy)
        admin $2a$14$yR41x7U715c0mpr3ss10n.hashexamplevalue
    }
    
    reverse_proxy localhost:3000
}

Kita dapat membuat password hash menggunakan perintah berikut di terminal:

caddy hash-password --plaintext "password123"

10. `tls` (Konfigurasi Sertifikat & Enkripsi) #

Digunakan untuk menyesuaikan perilaku TLS Caddy, seperti menentukan email admin ACME, memuat sertifikat SSL berbayar secara manual, atau mengatur protokol minimum.

example.com {
    # Menggunakan sertifikat SSL berbayar atau custom yang sudah kita miliki
    tls /etc/ssl/certs/situs.pem /etc/ssl/private/situs.key
    
    # Atau mengonfigurasi opsi enkripsi modern
    tls {
        # Hanya izinkan TLS 1.3 demi keamanan maksimal
        protocols tls1.3
        
        # Menetapkan penyedia sertifikat kustom (misal: ZeroSSL)
        ca https://acme.zerossl.com/v2/DV90
    }
}

11. `log` (Access Log Sistem) #

Mengonfigurasi pencatatan data request masuk (access logs) untuk keperluan analitik lalu lintas atau audit keamanan.

example.com {
    log {
        # Tulis log ke berkas fisik di sistem
        output file /var/log/caddy/access.log {
            roll_size 100mb    # Putar file log setelah mencapai 100MB
            roll_keep 10       # Simpan maksimal 10 berkas log lama
            roll_keep_for 720h # Simpan log lama selama 30 hari (720 jam)
        }
        # Gunakan format JSON agar mudah dibaca oleh Elasticsearch atau Logstash
        format json
        level INFO
    }
    
    reverse_proxy localhost:3000
}

12. `php_fastcgi` (Pemrosesan PHP) #

Directive khusus yang sangat memudahkan konfigurasi web berbasis PHP (seperti WordPress, Laravel, atau Drupal) dengan meneruskan request file .php ke service PHP-FPM lokal secara otomatis.

example.com {
    root * /var/www/my-laravel-app/public
    
    # Teruskan request PHP ke unix socket PHP-FPM
    php_fastcgi unix//run/php/php8.2-fpm.sock {
        # Mengatur variabel environtment internal PHP jika dibutuhkan
        env PHP_ADMIN_VALUE "expose_php=Off \n memory_limit=256M"
    }
    
    file_server
}

Pola Kombinasi Directive (Production Use Cases) #

Di lingkungan produksi yang sesungguhnya, kita hampir selalu menggunakan kombinasi dari berbagai directive di atas. Berikut adalah contoh template konfigurasi siap pakai untuk berbagai kasus penggunaan umum:

1. Single Page Application (SPA) dengan Keamanan Maksimal #

Template ini cocok untuk menyajikan frontend berbasis React, Vue, Svelte, atau Angular yang diletakkan di server statis lokal.

app.mydomain.com {
    root * /var/www/dist
    
    # Aktifkan kompresi modern
    encode gzip zstd
    
    # Terapkan kumpulan header keamanan ketat
    header {
        Strict-Transport-Security "max-age=63072000; includeSubDomains; preload"
        X-Frame-Options "DENY"
        X-Content-Type-Options "nosniff"
        Referrer-Policy "strict-origin-when-cross-origin"
        Content-Security-Policy "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline';"
        -Server
        -X-Powered-By
    }
    
    # SPA Router fallback: arahkan request rute internal ke index.html
    @notFile {
        not file {path}
    }
    rewrite @notFile /index.html
    
    # Aktifkan penyajian berkas statis
    file_server
}

2. API Gateway dengan Konfigurasi CORS #

Jika Caddy bertindak sebagai gerbang terdepan untuk kluster API microservices kita dan harus melayani request lintas domain (Cross-Origin Resource Sharing).

api.mydomain.com {
    # Atur header CORS secara global untuk blok ini
    header {
        Access-Control-Allow-Origin "https://app.mydomain.com"
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers "Content-Type, Authorization, X-Requested-With"
        Access-Control-Allow-Credentials "true"
        Access-Control-Max-Age "3600"
    }
    
    # Intersepsi request pre-flight OPTIONS dari browser secara instan
    @options method OPTIONS
    respond @options "" 204
    
    # Teruskan request asli ke upstream API server
    reverse_proxy localhost:8080 {
        # Tambahkan header pelacakan IP asli client
        header_up X-Real-IP {remote_host}
    }
    
    # Konfigurasi log JSON
    log {
        output file /var/log/caddy/api_access.log {
            roll_size 50mb
        }
        format json
    }
}

3. WordPress Production Setup #

WordPress membutuhkan perlakuan khusus karena ia menggabungkan aset statis (gambar, CSS, JS), pemrosesan PHP, serta pemblokiran file konfigurasi sensitif.

blog.mydomain.com {
    root * /var/www/wordpress
    
    # Kompresi respon
    encode gzip zstd
    
    # Blokir akses ke berkas sensitif WordPress demi keamanan
    @blockSens {
        path /wp-config.php
        path /xmlrpc.php
        path /.env
        path /.git/*
    }
    respond @blockSens "Akses Ditolak" 403
    
    # Integrasi FastCGI untuk memproses berkas PHP
    php_fastcgi unix//run/php/php8.2-fpm.sock
    
    # Layani aset statis, sembunyikan file htaccess bawaan Apache jika ada
    file_server {
        hide .htaccess
    }
}

Ringkasan #

Directives adalah blok instruksi operasional Caddyfile yang diletakkan di dalam site block untuk memanipulasi request dan response.
reverse_proxy adalah tulang punggung integrasi backend aplikasi, sedangkan file_server adalah mesin penyaji berkas statis lokal.
rewrite bekerja secara internal di dalam server Caddy, sedangkan redir memicu pengalihan eksternal dengan mengirimkan response HTTP 3xx ke browser client.
Integrasi aplikasi PHP dapat diselesaikan dengan mudah menggunakan satu baris directive php_fastcgi yang diarahkan ke socket PHP-FPM.
header membantu kita mengamankan situs web dengan menghapus info server bawaan (-Server) dan menyuntikkan header keamanan modern.
Password untuk proteksi basicauth wajib dikonversi menjadi hash enkripsi bcrypt menggunakan perintah CLI caddy hash-password.

← Sebelumnya: Site Address Berikutnya: Matcher →

Directive #

Urutan Pemrosesan Request via Directive #

Anatomi Penulisan Directive #

1. Format Inline (Satu Baris) #

2. Format Blok #

3. Format Campuran (Inline & Blok) #

Penjelasan 10+ Directive Utama #

1. root (Menetapkan Folder Root) #

2. file_server (Menyajikan Berkas Statis) #

3. reverse_proxy (Proxy ke Backend Aplikasi) #

4. encode (Kompresi Konten) #

5. header (Manipulasi Header HTTP) #

6. redir (Pengalihan URL Eksternal) #

7. rewrite (Penulisan Ulang URI Internal) #

Perbedaan Fundamental: redir vs rewrite #

8. respond (Mengirimkan Response Langsung) #

9. basicauth (HTTP Basic Authentication) #

10. tls (Konfigurasi Sertifikat & Enkripsi) #

11. log (Access Log Sistem) #

12. php_fastcgi (Pemrosesan PHP) #