Global Options

Global Options #

Global options adalah blok konfigurasi khusus di Caddyfile yang mengontrol perilaku seluruh instance Caddy — bukan hanya satu site. Blok ini ditulis di bagian paling atas Caddyfile, sebelum blok site manapun, dan ditandai dengan kurung kurawal tanpa site address:

{
    # Global options di sini
    email [email protected]
}

example.com {
    # Site-specific config
}

Memahami global options penting karena banyak pengaturan yang tidak bisa dilakukan di level site harus dikonfigurasi di sini — termasuk email untuk notifikasi Let’s Encrypt, konfigurasi Admin API, port default HTTP/HTTPS, dan pengaturan TLS global.

Opsi yang Paling Sering Digunakan #

email — Email untuk ACME #

{
    # Email yang diberikan ke Let's Encrypt dan ZeroSSL
    # Digunakan untuk:
    # - Notifikasi jika sertifikat hampir expire dan renewal gagal
    # - Komunikasi terkait akun ACME
    # - Pemulihan akun jika ada masalah
    email [email protected]
}
Selalu set email di global options untuk deployment production. Tanpanya, Caddy tidak memberitahu kamu jika ada masalah dengan sertifikat. Let’s Encrypt akan mengirim email peringatan beberapa minggu sebelum sertifikat expire jika renewal gagal.

admin — Konfigurasi Admin API #

{
    # Default: Admin API aktif di localhost:2019
    # Tidak perlu ditulis jika ingin menggunakan default
    
    # Nonaktifkan Admin API (untuk environment yang tidak butuh)
    admin off
    
    # Ubah alamat listen
    admin localhost:2020
    
    # Ekspos ke jaringan internal (hati-hati!)
    admin 10.0.0.1:2019
    
    # Dengan konfigurasi detail
    admin localhost:2019 {
        origins localhost:2019 127.0.0.1:2019
        
        # Aktifkan enforcement origin untuk keamanan
        enforce_origin
    }
}

debug — Mode Debug #

{
    # Aktifkan logging debug untuk troubleshooting
    # JANGAN aktifkan di production — sangat verbose
    debug
}

log — Konfigurasi Log Global #

{
    # Log global untuk error dan startup messages
    log {
        # Output ke stderr (default untuk log error Caddy)
        output stderr
        
        # Atau ke file
        output file /var/log/caddy/caddy.log {
            roll_size 50mb
            roll_keep 5
        }
        
        # Level log: DEBUG, INFO, WARN, ERROR
        level INFO
        
        # Format
        format json
    }
}

Konfigurasi Port HTTP dan HTTPS #

{
    # Ubah port HTTP default (dari 80)
    http_port 8080
    
    # Ubah port HTTPS default (dari 443)
    https_port 8443
}

# Sekarang semua site listen di port kustom ini
# tanpa perlu menulis port di setiap site address
example.com {
    file_server
    # Otomatis listen di :8443 untuk HTTPS dan :8080 untuk HTTP redirect
}

Ini berguna untuk:

  • Development di port non-privileged tanpa root/capability
  • Deployment di belakang load balancer yang melakukan port mapping
  • Testing di CI/CD yang tidak bisa bind ke port < 1024

Konfigurasi ACME dan TLS Global #

acme_ca — Custom ACME CA #

{
    # Gunakan CA ACME yang berbeda (bukan Let's Encrypt default)
    
    # ZeroSSL
    acme_ca https://acme.zerossl.com/v2/DV90
    
    # Staging Let's Encrypt untuk testing (tidak di-trust browser)
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
    
    # Custom CA internal (untuk enterprise/intranet)
    acme_ca https://pki.internal.company.com/acme/directory
    
    email [email protected]
}
Gunakan staging CA Let’s Encrypt (acme-staging-v02) saat melakukan testing atau development untuk menghindari menghabiskan rate limit CA production. Sertifikat dari staging tidak di-trust browser, tapi fungsionalnya identik untuk testing.

acme_dns — DNS Provider Global #

{
    # Set DNS provider secara global untuk semua domain
    # Berguna jika semua domain menggunakan provider DNS yang sama
    acme_dns cloudflare {env.CLOUDFLARE_API_TOKEN}
    
    email [email protected]
}

# Semua site otomatis menggunakan DNS challenge
*.example.com {
    reverse_proxy localhost:3000
}

example.com {
    file_server
}

acme_eab — External Account Binding #

{
    # Untuk CA yang membutuhkan EAB (seperti ZeroSSL)
    acme_eab {
        key_id "your-key-id"
        mac_key "your-mac-key"
    }
    acme_ca https://acme.zerossl.com/v2/DV90
    email [email protected]
}

cert_issuer — Issuer Default #

{
    # Set issuer TLS default untuk semua site
    cert_issuer acme {
        ca https://acme.zerossl.com/v2/DV90
        email [email protected]
    }
    
    # Atau gunakan internal CA untuk semua site
    # (berguna untuk intranet/development)
    # cert_issuer internal
}

On-Demand TLS #

{
    # Aktifkan On-Demand TLS
    # Caddy akan mendapatkan sertifikat saat pertama kali
    # ada request untuk domain yang belum punya sertifikat
    on_demand_tls {
        # Endpoint yang dikonsultasikan untuk setiap domain baru
        # Harus return HTTP 200 jika domain valid, non-200 jika tidak
        ask https://your-api.example.com/check-domain
        
        # Rate limiting untuk mencegah abuse
        interval 2m    # Maksimal satu sertifikat baru per 2 menit
        burst 5        # Atau maksimal 5 dalam satu burst
    }
    
    email [email protected]
}

# Gunakan on_demand di dalam blok site
:443 {
    tls {
        on_demand
    }
    reverse_proxy localhost:3000
}

On-Demand TLS sangat berguna untuk platform multi-tenant di mana domain customer tidak diketahui di muka.

Konfigurasi Server HTTP #

{
    servers {
        # Protokol yang didukung
        protocols h1 h2 h3
        
        # Trusted proxies — IP yang dipercaya untuk X-Forwarded-For
        # Penting jika Caddy berada di belakang load balancer
        trusted_proxies static 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
        
        # Client IP header yang digunakan (jika ada custom header)
        client_ip_headers X-Real-IP X-Forwarded-For
        
        # Timeouts global
        timeouts {
            read_body   10s
            read_header 10s
            write       30s
            idle        120s
        }
        
        # Batasi ukuran request body (default: tidak terbatas)
        max_header_size 1mb
    }
}

Konfigurasi Trusted Proxies yang Benar #

Ini adalah pengaturan yang sangat penting jika Caddy berada di belakang load balancer (AWS ALB, Cloudflare, Nginx, dll):

{
    servers {
        # Tanpa trusted_proxies:
        # {remote_host} akan berisi IP load balancer, bukan IP client sebenarnya
        
        # Dengan trusted_proxies:
        # Caddy membaca X-Forwarded-For dari proxy yang dipercaya
        # {remote_host} akan berisi IP client sebenarnya
        trusted_proxies static {
            # IP load balancer / proxy yang kamu percaya
            10.0.0.0/8
            172.16.0.0/12
            192.168.0.0/16
            
            # Cloudflare IP ranges (jika menggunakan Cloudflare)
            # 103.21.244.0/22
            # 103.22.200.0/22
            # ... (lihat dokumentasi Cloudflare untuk list lengkap)
        }
    }
}

Konfigurasi Storage Sertifikat #

{
    # Default: simpan sertifikat di filesystem lokal
    # Ubah storage untuk deployment multi-instance
    
    storage file_system {
        root /custom/path/to/certs
    }
    
    # Untuk deployment terdistribusi, gunakan Redis (dengan plugin)
    # storage redis {
    #     host     localhost
    #     port     6379
    #     password {env.REDIS_PASSWORD}
    #     key_prefix caddy
    # }
    
    # Atau Consul (dengan plugin)
    # storage consul {
    #     address localhost:8500
    #     prefix caddy
    # }
}

Auto HTTPS dan TLS Settings #

{
    # Nonaktifkan HTTPS otomatis untuk semua site
    # Berguna untuk server di jaringan internal yang tidak butuh TLS
    auto_https off
    
    # Nonaktifkan hanya redirect HTTP → HTTPS
    # (HTTPS tetap aktif, tapi tidak ada redirect dari port 80)
    auto_https disable_redirects
    
    # Nonaktifkan sertifikat Let's Encrypt tapi tetap ada redirect
    auto_https disable_certs
    
    email [email protected]
}

Konfigurasi Lengkap untuk Production #

Ini adalah contoh global options yang komprehensif untuk deployment production:

{
    # Email untuk Let's Encrypt notifications
    email [email protected]
    
    # Admin API — hanya dari localhost
    admin localhost:2019 {
        origins localhost:2019
    }
    
    # Log global Caddy (bukan access log — itu dikonfigurasi per-site)
    log {
        output file /var/log/caddy/caddy.log {
            roll_size 50mb
            roll_keep 5
            roll_keep_for 336h
        }
        format json
        level WARN    # Hanya warning dan error di production
    }
    
    # Server settings
    servers {
        protocols h1 h2 h3
        
        # Trusted proxies untuk deployments di belakang load balancer
        trusted_proxies static 10.0.0.0/8 172.16.0.0/12 192.168.0.0/16
        
        timeouts {
            read_body   30s
            read_header 10s
            write       60s
            idle        120s
        }
    }
    
    # TLS global settings
    cert_issuer acme {
        ca https://acme-v02.api.letsencrypt.org/directory
        email [email protected]
    }
}

Konfigurasi untuk Development #

{
    # Development mode
    
    # HTTP di port tinggi (tanpa perlu root/capability)
    http_port 8080
    https_port 8443
    
    # Internal CA untuk localhost
    local_certs
    
    # Debug logging untuk troubleshooting
    debug
    
    # Admin API default (localhost:2019)
    # Tidak perlu diubah untuk development
}

localhost:8443 {
    tls internal
    reverse_proxy localhost:3000
}

localhost:8080 {
    redir https://localhost:8443{uri}
}

Referensi Cepat: Semua Global Options Penting #

{
    # ─── ACME / TLS ───────────────────────────────────────────
    email             [email protected]
    acme_ca           https://acme-v02.api.letsencrypt.org/directory
    acme_dns          cloudflare {env.CF_TOKEN}
    acme_eab          { key_id "id" mac_key "key" }
    cert_issuer       acme { ... }
    local_certs                         # Gunakan internal CA
    skip_install_trust                  # Jangan install root CA
    auto_https        off               # Nonaktifkan HTTPS otomatis
    on_demand_tls     { ask https://... interval 2m burst 5 }

    # ─── SERVER ───────────────────────────────────────────────
    http_port         80
    https_port        443
    
    servers {
        protocols       h1 h2 h3
        trusted_proxies static 10.0.0.0/8
        timeouts {
            read_body   30s
            read_header 10s
            write       60s
            idle        120s
        }
    }

    # ─── ADMIN API ────────────────────────────────────────────
    admin             localhost:2019
    admin             off              # Nonaktifkan

    # ─── LOGGING ──────────────────────────────────────────────
    log {
        output        file /var/log/caddy/caddy.log
        format        json
        level         WARN
    }
    debug                             # Aktifkan debug logging

    # ─── STORAGE ──────────────────────────────────────────────
    storage file_system {
        root /custom/path
    }

    # ─── MISC ─────────────────────────────────────────────────
    grace_period      5s              # Shutdown grace period
    shutdown_delay    0s              # Delay sebelum shutdown dimulai
}

Ringkasan #

  • Blok global options ({ ... } tanpa site address) harus berada di bagian paling atas Caddyfile, sebelum blok site manapun.
  • Selalu set email di production untuk notifikasi Let’s Encrypt jika ada masalah dengan renewal.
  • admin off untuk menonaktifkan Admin API di environment yang tidak membutuhkannya.
  • trusted_proxies sangat penting jika Caddy berada di belakang load balancer — tanpanya, IP client yang dilaporkan adalah IP load balancer, bukan IP client sebenarnya.
  • auto_https off untuk menonaktifkan HTTPS otomatis di server internal atau development yang tidak butuh TLS.
  • debug untuk troubleshooting — tapi jangan dibiarkan aktif di production karena sangat verbose.
  • Gunakan staging CA (acme-staging-v02) saat testing untuk menghindari rate limit production.

← Sebelumnya: Snippet & Import   Berikutnya: Konsep ACME →

About | Author | Content Scope | Editorial Policy | Privacy Policy | Disclaimer | Contact