Belajar Caddy - Admin API & Dynamic Configuration

#Pendahuluan

Caddyfile adalah pintu utama, tapi ada jalan lain: admin API. Melalui HTTP di port 2019, kalian bisa membaca, mengganti, dan mem-patch konfigurasi Caddy saat berjalan — tanpa restart, tanpa downtime. Episode 23 membuka kekuatan dynamic configuration ini.

#Admin API: Dasar

#Endpoint dan Akses

Admin API tersedia di localhost:2019 secara default. Endpoint utamanya:

• GET /config/ — baca konfigurasi saat ini.
• POST /load — muat konfigurasi baru sepenuhnya.
• PATCH /config/... — ubah sebagian konfigurasi.
• POST /stop — hentikan Caddy secara mulus.
• GET /pki/... — info sertifikat.
• GET /metrics — metrics Prometheus (episode 22).

Contoh membaca konfigurasi:

curl http://localhost:2019/config/

curl http://localhost:2019/config/ mengembalikan JSON lengkap konfigurasi yang sedang berjalan.

#Mengamankan Admin API

Secara default admin API hanya mendengarkan di localhost. Jika harus diakses jarak jauh, batasi akses:

{
    admin 127.0.0.1:2019
}
 
example.com {
    root * /var/www
    file_server
}

#Memuat Konfigurasi JSON

#Format JSON Native

Caddy memahami JSON secara native. Konfigurasi minimum:

{
    "apps": {
        "http": {
            "servers": {
                "srv0": {
                    "listen": [":8080"],
                    "routes": [
                        {
                            "handle": [
                                {
                                    "handler": "static_response",
                                    "body": "Halo dari JSON"
                                }
                            ]
                        }
                    ]
                }
            }
        }
    }
}

JSON ini melayani respons statis di port 8080. Struktur JSON jauh lebih verbose dari Caddyfile — karena itu Caddyfile tetap pilihan utama untuk manusia.

#Memuat via API

Kirim konfigurasi JSON ke Caddy:

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

curl -X POST -d @config.json memuat konfigurasi baru. Perubahan langsung berlaku — ini adalah hot reload.

#Hot Reload dan Patch

#Mengganti Konfigurasi Tanpa Downtime

Dua pola mengubah konfigurasi:

• POST /load: ganti seluruh konfigurasi sekaligus.
• PATCH /config: ubah hanya bagian tertentu.

Contoh patch menambah reverse proxy:

curl -X PATCH -H 'Content-Type: application/json' \
     -d '{"handler": "reverse_proxy", "upstreams": [{"dial": "localhost:8080"}]}' \
     http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0

PATCH menargetkan path JSON tertentu dan mengganti hanya bagian itu. Koneksi yang sedang aktif tidak terputus — Caddy menangani transisi secara mulus.

#Caddyfile Adapter

Untuk kemudahan, kirim Caddyfile dan biarkan Caddy mengadaptasinya:

curl -X POST -H 'Content-Type: text/caddyfile' \
     --data-binary @Caddyfile \
     http://localhost:2019/load

--data-binary @Caddyfile dengan content type text/caddyfile memberi tahu Caddy untuk mengadaptasi Caddyfile ke JSON dulu, lalu memuatnya. Keduanya valid — pilih sesuai kebutuhan.

#JSON vs Caddyfile

#Kapan Memakai Masing-Masing

• Caddyfile: untuk konfigurasi yang dibaca manusia, version control, dan setup tetap.
• JSON: untuk konfigurasi yang dihasilkan program, otomasi, dan integrasi infrastruktur.
• API: untuk perubahan runtime tanpa memuat ulang file.

Kalian bisa melihat JSON hasil konversi Caddyfile:

caddy adapt --config Caddyfile --pretty

caddy adapt --pretty mencetak JSON yang mudah dibaca. Ini cara terbaik mempelajari struktur JSON dari Caddyfile yang sudah kalian kenal.

#Otomasi dan Multi-Tenant

#CI/CD Integration

Admin API cocok untuk pipeline deployment:

1. CI build menghasilkan Caddyfile atau JSON baru.
2. Validasi konfigurasi (episode 30).
3. Kirim ke admin API Caddy produksi.
4. Perubahan aktif tanpa restart.

#Dynamic Backend Registration

Skenario nyata: service mesh mendaftarkan backend baru secara dinamis:

curl -X POST -H 'Content-Type: application/json' \
     -d '{"dial": "service-b:8081"}' \
     http://localhost:2019/config/apps/http/servers/srv0/routes/0/handle/0/upstreams

Endpoint PATCH/POST per-upstream memungkinkan menambah dan menghapus backend tanpa menyentuh seluruh konfigurasi. Ini fondasi service discovery dinamis yang dipakai di orchestration.

#Infrastructure as Code

Gabungkan Caddyfile (version control) dan admin API (runtime) untuk Infrastructure as Code yang lengkap: konfigurasi versi terkontrol di repositori, perubahan runtime dilakukan lewat API yang terdokumentasi, dan state akhir bisa dibaca ulang lewat GET /config/.

#Penutup

Episode 23 membuka admin API: endpoint konfigurasi dan metrics, memuat serta mengganti JSON dengan POST /load dan PATCH, hot reload tanpa downtime, perbandingan JSON vs Caddyfile dengan adapter, dan skenario otomasi CI/CD, dynamic backend, serta multi-tenant.

Inti yang harus dibawa pulang:

• Admin API berjalan di localhost:2019 secara default.
• POST /load mengganti konfigurasi, PATCH mengubah sebagian.
• Perubahan berlaku tanpa downtime.
• caddy adapt --pretty mengubah Caddyfile menjadi JSON.
• Jangan pernah ekspos admin API ke publik tanpa pengamanan.
• API memungkinkan dynamic backend dan Infrastructure as Code.

Di episode 24 selanjutnya kita akan membahas PHP-FPM integration — directive php_fastcgi, koneksi via Unix socket dan TCP, setup PHP-FPM dengan pool, pola WordPress, Laravel, dan Symfony dengan try_files, serta optimasi OPcache dan FPM process management.