Global Options #

Saat kita mengonfigurasi Caddyfile, sebagian besar waktu kita dihabiskan untuk mengatur perilaku spesifik dari masing-masing website atau rute API di dalam blok situs (site block). Namun, ada banyak parameter operasional yang tidak ditujukan untuk situs tertentu, melainkan berlaku untuk seluruh instance server Caddy yang sedang berjalan.

Pengaturan tingkat global ini mencakup penentuan alamat email untuk pendaftaran sertifikat SSL ke Let’s Encrypt secara global, mengubah perilaku Admin API, mengaktifkan mode pemecahan masalah (debug logging), mendefinisikan port default HTTP/HTTPS kustom, hingga mengonfigurasi sinkronisasi penyimpanan sertifikat dalam kluster server (cluster storage). Di Caddyfile, semua setelan instansi ini dikumpulkan di dalam satu blok khusus yang berada di baris paling atas berkas, yang disebut sebagai Global Options Block.

Alur Penerbitan Sertifikat On-Demand TLS via Ask API #

Salah satu fitur tingkat global yang paling membutuhkan koordinasi eksternal adalah On-Demand TLS. Di sini, Caddy berinteraksi dengan API internal kita untuk memeriksa keabsahan domain baru sebelum meminta sertifikat SSL ke otoritas sertifikat (CA).

Untuk memvisualisasikan bagaimana proses koordinasi sertifikat dinamis ini berjalan, mari kita perhatikan diagram urutan (sequence diagram) berikut:

sequenceDiagram
    autonumber
    participant Client as "Client (Browser)"
    participant Caddy as "Caddy Web Server"
    participant API as "Ask API (localhost:5000)"
    participant CA as "ACME CA (Let's Encrypt)"

    Client->>Caddy: "SSL Client Hello (domain: app.customer.com)"
    note over Caddy: Caddy mendeteksi domain baru & opsi on_demand aktif
    Caddy->>API: "GET /validate-domain?domain=app.customer.com"
    API-->>Caddy: "HTTP 200 OK (Domain Valid & Diizinkan)"
    Caddy->>CA: "Request sertifikat dinamis (ACME Challenge)"
    CA-->>Caddy: "Kirim Tantangan Validasi (DNS/HTTP-01)"
    Caddy-->>CA: "Selesaikan Tantangan & Dapatkan Sertifikat SSL"
    note over Caddy: Caddy menyimpan sertifikat di Storage & memuat ke memory
    Caddy-->>Client: "SSL Server Hello (Koneksi HTTPS Berhasil)"

Sintaksis Global Options Block #

Sintaksis blok opsi global ditandai dengan sepasang kurung kurawal { } tanpa menyertakan nama domain atau alamat situs apa pun di depannya. Blok ini wajib diletakkan di bagian paling atas berkas Caddyfile, sebelum blok situs apa pun dideklarasikan.

# Blok Opsi Global — Wajib di baris pertama
{
    # Opsi global diletakkan di sini
    email [email protected]
    debug
}

# Blok Situs 1
example.com {
    file_server
}

# Blok Situs 2
api.example.com {
    reverse_proxy localhost:8080
}

Jika kita meletakkan blok opsi global di tengah atau di bawah berkas setelah blok situs lain, parser Caddyfile akan mengalami kegagalan (syntax error) karena mengira blok tersebut adalah deklarasi blok situs tanpa alamat yang tidak valid.

Tabel Analitik Opsi Global Paling Kritis di Production #

Untuk memastikan instansi Caddy kita aman, andal, dan siap menangani lalu lintas data tinggi, ada beberapa opsi global yang wajib dikonfigurasi secara hati-hati. Tabel berikut merangkum dampak dari parameter kustom tersebut:

Pembahasan Opsi Global yang Paling Sering Digunakan #

Berikut adalah penjelasan detail mengenai parameter konfigurasi instansi yang dapat kita setel di dalam blok opsi global:

1. email (Kontak Otoritas Sertifikat ACME) #

Menetapkan alamat email administratif yang akan didaftarkan ke Let’s Encrypt atau ZeroSSL saat Caddy meminta sertifikat SSL.

{
    email [email protected]
}

[!TIP] Selalu konfigurasi parameter email di server produksi. Tanpa email, Let’s Encrypt tidak memiliki cara untuk menghubungi Anda jika terjadi kegagalan pembaruan (renewal) otomatis yang dapat menyebabkan sertifikat SSL kedaluwarsa, atau untuk mengirimkan pengumuman keamanan kritis terkait infrastruktur sertifikat.

2. admin (Mengontrol Admin API Caddy) #

Caddy memiliki API administratif berbasis HTTP (secara default aktif di localhost:2019) yang memungkinkan kita memuat ulang konfigurasi tanpa downtime, melihat status server, atau menghentikan instansi Caddy secara dinamis.

{
    # Opsi A: Matikan Admin API sepenuhnya demi keamanan maksimal
    admin off
    
    # Opsi B: Ubah port atau interface listen API admin
    admin localhost:2025
    
    # Opsi C: Konfigurasi keamanan detail
    admin localhost:2019 {
        # Hanya izinkan request yang memiliki header Origin berikut
        origins localhost:2019 127.0.0.1:2019
        enforce_origin
    }
}

3. debug (Mode Pelacakan Detail) #

Mengaktifkan log tingkat detail (verbose logs) untuk membantu kita melacak alur request HTTP, proses jabat tangan TLS, atau kendala koneksi ke server upstream backend.

{
    # Aktifkan mode debug
    debug
}

Jangan biarkan mode ini aktif di server produksi yang melayani lalu lintas padat, karena volume log yang dihasilkan sangat besar dan dapat memenuhi kapasitas penyimpanan disk dalam waktu singkat.

4. log (Konfigurasi Log Sistem Global) #

Mengatur pencatatan aktivitas startup server Caddy, proses sertifikasi, serta log kegagalan internal instansi (berbeda dengan access log lalu lintas situs yang diatur di dalam blok situs).

{
    log {
        # Tulis log global ke berkas fisik
        output file /var/log/caddy/system.log {
            roll_size 50mb
            roll_keep 3
        }
        # Gunakan format JSON agar mudah dibaca mesin parser log
        format json
        level WARN # Hanya rekam log tingkat Warning dan Error
    }
}

5. http_port & https_port (Port Default Kustom) #

Secara bawaan, Caddy berjalan di port standar web, yaitu 80 untuk HTTP dan 443 untuk HTTPS. Kita dapat mengubah port default ini jika Caddy dijalankan di lingkungan non-root (tidak memiliki hak akses bind port di bawah 1024) atau di belakang load balancer eksternal.

{
    http_port 8080
    https_port 8443
}

# Sekarang domain di bawah akan otomatis listen di port 8443 untuk HTTPS
# dan port 8080 untuk HTTP redirect
myplatform.com {
    file_server
}

TLS & ACME Global Settings #

Jika kita memiliki banyak blok situs dan ingin menyelaraskan bagaimana sertifikat TLS diperoleh dan divalidasi, kita dapat menetapkan aturan TLS global:

1. acme_ca (Custom Certificate Authority) #

Mengalihkan Caddy dari menggunakan Let’s Encrypt default ke penyedia sertifikat ACME lainnya.

{
    # Opsi A: Gunakan Let's Encrypt Staging (Sangat direkomendasikan untuk uji coba)
    # untuk menghindari pemblokiran rate-limit produksi Let's Encrypt
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
    
    # Opsi B: Gunakan ZeroSSL
    # acme_ca https://acme.zerossl.com/v2/DV90
}

2. acme_dns (DNS Provider Global) #

Menetapkan modul DNS challenge secara global untuk semua domain yang membutuhkan validasi sertifikat via DNS (seperti domain wildcard).

{
    acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
}

3. local_certs (CA Internal untuk Semua Situs) #

Memaksa Caddy untuk menggunakan CA internal miliknya sendiri untuk menerbitkan sertifikat SSL bagi semua domain, bukan meminta sertifikat publik dari Let’s Encrypt. Sangat berguna untuk intranet perusahaan atau lab pengembangan tertutup.

{
    local_certs
}

Konfigurasi Server HTTP & Trusted Proxies #

Di dalam opsi global, kita dapat mengatur perilaku detail dari engine HTTP server Caddy melalui blok servers:

{
    servers {
        # Batasi protokol TLS yang aktif
        protocols h1 h2 h3 # Aktifkan HTTP/1.1, HTTP/2, dan HTTP/3
        
        # Atur batas waktu koneksi (timeout) secara global
        timeouts {
            read_body   30s
            read_header 10s
            write       60s
            idle        120s
        }
        
        # Konfigurasi Trusted Proxies (SANGAT PENTING!)
        # Jika Caddy berada di belakang CDN (Cloudflare) atau Load Balancer (AWS ALB, Nginx)
        trusted_proxies static 10.0.0.0/8 192.168.1.0/24
        
        # Jika kita ingin mengubah header mana yang digunakan untuk mengidentifikasi IP client
        client_ip_headers CF-Connecting-IP X-Forwarded-For
    }
}

Mengapa trusted_proxies Sangat Krusial? #

Jika server Caddy kita berada di belakang Load Balancer, maka setiap request HTTP yang masuk ke Caddy akan terlihat seolah-olah berasal dari alamat IP Load Balancer tersebut, bukan dari IP asli client/pengguna. Akibatnya:

1. Log lalu lintas data kita akan dipenuhi oleh IP Load Balancer.
2. Pembatasan akses berbasis IP (IP Whitelisting atau Geoblocking) tidak akan berfungsi karena IP yang terdeteksi salah.

Dengan mendefinisikan alamat IP Load Balancer kita di dalam parameter trusted_proxies, kita memberi tahu Caddy untuk mempercayai header X-Forwarded-For yang dikirimkan oleh Load Balancer tersebut. Caddy kemudian akan mengekstrak IP asli client dari header tersebut dan menuliskannya ke variabel {remote_host}.

Berikut adalah contoh konfigurasi untuk mempercayai IP range Cloudflare secara manual:

{
    servers {
        # Daftar IP Range Cloudflare IPv4 (Sebagian sebagai ilustrasi)
        trusted_proxies static {
            173.245.48.0/20
            103.21.244.0/22
            103.22.200.0/22
            103.31.4.0/22
            141.101.64.0/18
            108.162.192.0/18
            190.93.240.0/20
            188.114.96.0/20
            197.234.240.0/22
            198.41.128.0/17
        }
    }
}

Menyetel Perilaku Auto HTTPS (Opsi Penonaktifan) #

Caddy memicu penanganan TLS otomatis secara agresif demi memastikan web aman. Namun, dalam skenario di mana TLS dihentikan di tingkat Load Balancer terluar (TLS termination), server Caddy kita hanya bertindak sebagai penerima HTTP biasa. Caddy menyediakan kontrol detail untuk menyesuaikan hal ini:

1. auto_https off #

Menonaktifkan semua kapabilitas otomatisasi HTTPS Caddy, termasuk pembuatan sertifikat Let’s Encrypt dan pengalihan port 80. Caddy berperilaku seperti web server HTTP tradisional.

{
    auto_https off
}

2. auto_https disable_redirects #

Sertifikat TLS tetap dibuat dan diaktifkan di port 443, tetapi Caddy tidak akan membuat server pengalihan otomatis di port 80. Pengguna yang mengetikkan alamat http:// tidak akan dialihkan ke https:// secara otomatis. Sangat berguna jika Anda ingin menangani port 80 secara manual untuk rute khusus.

{
    auto_https disable_redirects
}

3. auto_https disable_certs #

Caddy tetap mengaktifkan pengalihan lalu lintas HTTP ke HTTPS, tetapi tidak mencoba membuat sertifikat SSL publik. Opsi ini digunakan jika Anda ingin Caddy melayani HTTPS menggunakan sertifikat yang Anda muat secara manual di blok situs.

{
    auto_https disable_certs
}

Cluster Storage (Penyimpanan Tersinkronisasi) #

Secara bawaan, Caddy menyimpan file sertifikat SSL dan kunci privat di dalam sistem berkas lokal (local filesystem) server tersebut. Jalur penyimpanan default bervariasi sesuai sistem operasi, seperti /var/lib/caddy/.local/share/caddy pada Linux systemd, atau ~/.local/share/caddy pada user standar.

Namun, jika kita menjalankan Caddy di dalam lingkungan multi-server (cluster / load-balanced pool), setiap server Caddy harus memiliki akses ke sertifikat yang sama agar tidak meminta sertifikat baru secara berulang-ulang ke Let’s Encrypt yang dapat memicu rate-limit block.

Caddy mengelola konflik antar-server ini dengan menerapkan mekanisme distributed locks (kunci terdistribusi) pada storage yang digunakan. Kita dapat mengonfigurasi penyimpanan terdistribusi menggunakan plugin storage Redis atau Consul:

{
    # Opsi A: Sinkronisasi menggunakan Redis Cluster
    storage redis {
        host     "redis-cluster.internal"
        port     6379
        password {env.REDIS_PASSWORD}
        key_prefix "caddy_certs"
    }
    
    # Opsi B: Sinkronisasi menggunakan HashiCorp Consul
    # storage consul {
    #     address "consul.internal:8500"
    #     prefix "caddy"
    # }
}

Contoh Konfigurasi Lengkap #

1. Template untuk Server Produksi (Production Setup) #

{
    # Email utama untuk notifikasi SSL
    email [email protected]
    
    # Log global sistem Caddy
    log {
        output file /var/log/caddy/caddy_system.log {
            roll_size 100mb
            roll_keep 7
        }
        format json
        level WARN # Hanya catat Warning & Error
    }
    
    # Penyetelan HTTP Engine & Load Balancer Trust
    servers {
        protocols h1 h2 h3
        trusted_proxies static 10.0.0.0/8 172.16.0.0/12
        timeouts {
            read_header 5s
            idle 120s
        }
    }
    
    # Konfigurasi Cluster Storage menggunakan Redis
    storage redis {
        host "redis-prod.company.lan"
        password {env.REDIS_ACCESS_PASSWORD}
    }
}

# Blok situs production kita
myfirm.com {
    reverse_proxy localhost:3000
}

2. Template untuk Mesin Uji Coba (Development Setup) #

{
    # Jalankan di port non-privileged (tidak butuh sudo/root)
    http_port 8080
    https_port 8443
    
    # Gunakan CA internal (sertifikat lokal gratis tanpa internet)
    local_certs
    
    # Aktifkan debug logging untuk memantau request detail di terminal
    debug
    
    # Pertahankan konfigurasi admin API di port default
    admin localhost:2019
}

# Blok situs development lokal kita
localhost:8443 {
    tls internal
    reverse_proxy localhost:3000
}

Ringkasan #

• Global Options Block ditulis menggunakan kurung kurawal {} tanpa nama domain, dan wajib diletakkan di baris pertama berkas Caddyfile.
• Mengonfigurasi email di tingkat global sangat penting agar kita menerima notifikasi Let’s Encrypt jika ada kegagalan pembaruan otomatis sertifikat SSL.
• Parameter trusted_proxies di bawah blok servers wajib dikonfigurasi jika Caddy berjalan di belakang load balancer eksternal atau CDN untuk memastikan IP client terdeteksi secara akurat.
• Gunakan acme_ca Let’s Encrypt Staging saat melakukan pengujian konfigurasi baru agar tidak terkena pembatasan kuota (rate limit) sertifikat Let’s Encrypt produksi.
• Konfigurasikan storage berbasis database terdistribusi seperti Redis jika server Caddy kita berjalan di lingkungan multi-server kluster di belakang load balancer.

← Sebelumnya: Snippet & Import   Berikutnya: Konsep ACME →