Error Umum #

Mengetahui berbagai kesalahan (error) yang paling sering terjadi dan memahami cara mengatasinya secara taktis dapat menghemat waktu berjam-jam saat melakukan pemecahan masalah (troubleshooting). Sebagai server web modern, Caddy memberikan pesan kesalahan yang cukup jelas, namun sering kali akar permasalahannya terletak pada interaksi antara Caddy, konfigurasi sistem operasi, jaringan, atau aplikasi backend kita. Artikel ini mengompilasi daftar kesalahan paling umum yang dihadapi pengguna Caddy di lingkungan produksi beserta langkah-langkah solutif yang sudah teruji.

Diagram Pemecahan Masalah Koneksi & TLS #

Sebelum masuk ke detail teknis setiap kesalahan, kita dapat menggunakan diagram alir keputusan (decision tree) di bawah ini sebagai panduan cepat untuk mengisolasi masalah jaringan dan sertifikat SSL/TLS pada Caddy:

flowchart TD
    Start["Klien Mengalami Error"] --> Type{"Jenis Masalah?"}
    
    Type -->|"Koneksi Gagal / Timeout"| PortCheck{"Port 80 atau 443 Terbuka?"}
    PortCheck -- Tidak --> Firewall["Periksa Firewall, Security Group & Port Binding (lsof)"]
    PortCheck -- Ya --> BackendCheck{"Backend Service Aktif?"}
    BackendCheck -- Tidak --> RunBackend["Jalankan Backend & Periksa Port (curl / ss)"]
    BackendCheck -- Ya --> ProxyConfig["Periksa Konfigurasi reverse_proxy & Target Port Caddyfile"]
    
    Type -->|"TLS / SSL Error"| DNSCheck{"DNS Resolve ke IP Server?"}
    DNSCheck -- Tidak --> UpdateDNS["Perbarui A/AAAA Record DNS Domain"]
    DNSCheck -- Ya --> ACMEType{"Jenis Tantangan ACME?"}
    ACMEType -->|HTTP-01| HTTPPort["Pastikan Port 80 Terbuka ke Internet & Nonaktifkan Cloudflare Proxy Sementara"]
    ACMEType -->|DNS-01| DNSToken["Periksa API Token DNS & Izin Menulis Berkas Kredensial"]
    ACMEType -->|Local PKI| LocalTrust["Jalankan caddy trust pada Mesin Klien"]
    
    style Start stroke:#0288d1,stroke-width:2px
    style Type stroke:#7b1fa2,stroke-width:2px

1. Port Already in Use #

Gejala Kesalahan #

Ketika mencoba menjalankan Caddy secara manual atau memulai layanan via systemd, kita melihat pesan kesalahan berikut di log sistem:

Error: listen tcp :443: bind: address already in use
Error: listen tcp :80: bind: address already in use

Penyebab Utama #

Setiap alamat IP dan port pada sistem operasi hanya dapat diduduki (bound) oleh satu proses aplikasi pada satu waktu. Pesan di atas menandakan ada aplikasi lain (seperti Nginx, Apache HTTPD, HAProxy, atau instansi Caddy lain yang berjalan di latar belakang) yang sudah menduduki port HTTP (80) atau HTTPS (443).

Langkah Diagnosis & Solusi #

Kita perlu mengidentifikasi proses mana yang menggunakan port tersebut dan menghentikannya sebelum memulai Caddy:

# 1. Cari nama proses dan PID yang menduduki port 80 dan 443
sudo lsof -i :80
sudo lsof -i :443

# Alternatif menggunakan perintah ss (lebih cepat di Linux modern)
sudo ss -tlnp | grep -E ':80|:443'

# Output contoh:
# LISTEN 0 128 0.0.0.0:443 0.0.0.0:* users:(("nginx",pid=1234,fd=6))

# 2. Hentikan layanan yang berkonflik jika dikenali
sudo systemctl stop nginx      # Jika sistem menggunakan Nginx
sudo systemctl stop apache2    # Jika sistem menggunakan Apache

# 3. Jika itu adalah instansi Caddy liar yang tidak dikelola systemd, hentikan paksa
sudo kill -9 1234              # Ganti 1234 dengan PID hasil pelacakan di atas

# 4. Jalankan kembali layanan Caddy kita
sudo systemctl start caddy

2. Permission Denied di Port < 1024 #

Gejala Kesalahan #

Saat kita menjalankan binary Caddy menggunakan pengguna biasa (non-root), Caddy menolak berjalan dan mengeluarkan log:

Error: listen tcp :443: bind: permission denied

Penyebab Utama #

Sistem operasi berbasis UNIX (termasuk Linux dan macOS) membatasi akses pengikatan port di bawah 1024 (dikenal sebagai privileged ports atau well-known ports) hanya untuk pengguna dengan hak istimewa tinggi (root atau superuser). Ini adalah tindakan keamanan untuk mencegah pengguna biasa menyamar sebagai layanan sistem resmi.

Langkah Diagnosis & Solusi #

Kita sangat tidak disarankan menjalankan server web produksi langsung sebagai pengguna root demi mematuhi asas hak akses minimal (principle of least privilege). Sebagai gantinya, gunakan salah satu solusi berikut:

# Solusi 1: Berikan kapabilitas khusus (Capabilities) pada binary Caddy
# Ini mengizinkan binary Caddy melakukan port binding port rendah tanpa hak akses root penuh
sudo setcap cap_net_bind_service=+ep $(which caddy)

# Verifikasi apakah kapabilitas berhasil ditambahkan
getcap $(which caddy)
# Output yang benar: /usr/bin/caddy = cap_net_bind_service+ep

# Solusi 2: Jika menggunakan Systemd (Sangat direkomendasikan untuk produksi)
# Pastikan file unit systemd (/etc/systemd/system/caddy.service) memiliki opsi berikut:
# [Service]
# User=caddy
# Group=caddy
# AmbientCapabilities=CAP_NET_BIND_SERVICE
# CapabilityBoundingSet=CAP_NET_BIND_SERVICE

3. TLS Certificate Error (ACME Challenge Failed) #

Gejala Kesalahan #

Sertifikat SSL/TLS tidak berhasil diterbitkan, browser menampilkan peringatan Your connection is not private, dan log Caddy mencatat:

Error: obtaining certificate: ...
Error: ACME challenge failed
Error: HTTP-01 challenge: could not connect to CA

Penyebab Utama #

Caddy menggunakan protokol ACME secara otomatis untuk meminta sertifikat dari Let’s Encrypt atau ZeroSSL. Tantangan standar yang digunakan adalah HTTP-01, yang mewajibkan server ACME dari luar internet dapat menghubungi Caddy di port 80 pada domain yang kita daftarkan. Kegagalan terjadi jika domain tidak mengarah ke IP server kita, port 80 diblokir oleh firewall, atau ada CDN proxy yang memutus koneksi.

Langkah Diagnosis & Solusi #

Lakukan investigasi terstruktur berikut untuk menemukan titik hambatan:

# 1. Pastikan DNS record (A dan AAAA) mengarah tepat ke IP publik server kita
dig +short example.com
# Output harus berupa IP publik server Anda. Jika kosong, perbarui DNS record Anda.

# 2. Periksa apakah port 80 dan 443 terbuka di firewall lokal (UFW / IPTables)
sudo ufw status
# Jika diblokir, izinkan lalu lintas HTTP & HTTPS:
sudo ufw allow proto tcp from any to any port 80,443

# 3. Uji apakah port 80 server Anda dapat dijangkau dari jaringan luar
# Kita bisa menggunakan curl dari mesin lain atau alat online seperti Let's Debug
curl -I http://example.com/.well-known/acme-challenge/test-probe

# 4. Skenario CDN (Cloudflare, dll.)
# Jika Anda mengaktifkan opsi "Proxy" (awan oranye) di Cloudflare, Cloudflare akan memblokir tantangan HTTP-01.
# Solusi: Matikan proxy Cloudflare (ubah ke DNS Only / awan abu-abu) secara sementara,
# atau beralih menggunakan DNS-01 Challenge dengan plugin caddy-dns.

4. 502 Bad Gateway #

Gejala Kesalahan #

Klien menerima kode status HTTP 502 Bad Gateway saat mencoba memuat halaman yang di-proxy, dan log Caddy menunjukkan kesalahan dialing upstream:

HTTP/1.1 502 Bad Gateway
Log: [error] dial tcp 127.0.0.1:3000: connect: connection refused

Penyebab Utama #

Caddy bertindak sebagai reverse proxy yang meneruskan permintaan ke aplikasi backend (seperti Node.js, Python FastAPI, Go, dll.). Status 502 berarti Caddy tidak dapat menjalin koneksi TCP atau UNIX socket dengan server backend tersebut. Ini biasanya karena backend mati, salah nomor port, atau masalah perizinan socket.

Langkah Diagnosis & Solusi #

Pastikan backend berjalan dan dengarkan di port yang sesuai dengan konfigurasi Caddyfile:

# 1. Uji koneksi langsung ke backend dari dalam server
curl -I http://localhost:3000/health
# Jika mengembalikan "connection refused", berarti backend mati.

# 2. Periksa status proses backend
sudo systemctl status my-backend-app
# Atau jika menggunakan PM2 untuk Node.js:
pm2 status

# 3. Periksa port yang diduduki oleh backend
sudo ss -tlnp | grep :3000
# Pastikan alamat binding adalah 127.0.0.1 atau 0.0.0.0 pada port yang benar.

# 4. Skenario UNIX Socket (Izin Berkas)
# Jika menggunakan socket file (misal php-fpm), pastikan user caddy memiliki hak baca-tulis:
# ANTI-PATTERN: Menyetel socket file dengan izin terlalu ketat (chmod 600) sehingga Caddy terblokir
# BENAR: Berikan kepemilikan kelompok (group ownership) ke user caddy
# chown php-user:caddy /var/run/php/php-fpm.sock
# chmod 660 /var/run/php/php-fpm.sock

5. 504 Gateway Timeout #

Gejala Kesalahan #

Klien menerima kode respons HTTP 504 Gateway Timeout setelah menunggu beberapa lama, dan log Caddy mencatat:

HTTP/1.1 504 Gateway Timeout
Log: [error] context deadline exceeded (client timeout while reading response headers)

Penyebab Utama #

Backend menerima permintaan dari Caddy, namun butuh waktu terlalu lama untuk menghasilkan respons (melebihi batas timeout bawaan Caddy). Hal ini sering terjadi pada operasi backend yang berat, seperti ekspor data besar, pemrosesan gambar, atau query database yang tidak dioptimalkan.

Langkah Diagnosis & Solusi #

Kita perlu menyesuaikan batas timeout pada bagian transport http di dalam blok reverse_proxy Caddyfile, serta menganalisis endpoint mana yang lambat:

# Mengatur batas timeout secara eksplisit di Caddyfile
example.com {
    reverse_proxy localhost:3000 {
        transport http {
            # Mengatur waktu tunggu pembacaan header respons (misal 60 detik)
            response_header_timeout 60s
            # Mengatur waktu tunggu pembacaan body respons
            read_timeout 120s
            # Mengatur waktu tunggu pengiriman request ke backend
            write_timeout 60s
        }
    }
}

# Lacak endpoint mana saja yang memicu latensi tinggi lewat access log Caddy
cat /var/log/caddy/access.log | \
    jq 'select(.duration > 5.0) | {timestamp: .ts, path: .request.uri, duration: .duration, status: .status}'

6. Syntax Error di Caddyfile #

Gejala Kesalahan #

Caddy menolak memuat ulang konfigurasi (reload) atau gagal dimulai, memunculkan pesan kesalahan parse yang membingungkan:

Error: parsing Caddyfile: Caddyfile:15 - Error during parsing: unrecognized directive: rverse_proxy

Penyebab Utama #

Ada kesalahan penulisan (typo) pada nama direktif, kurung kurawal {} yang tidak berpasangan, atau penulisan pencocok nama domain yang tidak sesuai dengan standar sintaksis Caddyfile.

Langkah Diagnosis & Solusi #

Jangan pernah melakukan pemuatan konfigurasi secara langsung di produksi tanpa divalidasi terlebih dahulu:

# 1. Jalankan utilitas verifikasi bawaan Caddy
caddy validate --config /etc/caddy/Caddyfile

# Output jika terjadi kesalahan:
# parsing Caddyfile tokens: /etc/caddy/Caddyfile:15 - Error during parsing: unrecognized directive: rverse_proxy

# 2. Segera buka file dan perbaiki baris 15 (ubah rverse_proxy menjadi reverse_proxy)
# 3. Jalankan adaptasi ke JSON untuk memastikan Caddyfile dapat diterjemahkan dengan sempurna
caddy adapt --config /etc/caddy/Caddyfile > /dev/null

7. TLS Handshake Error (tls: no certificate available) #

Gejala Kesalahan #

Koneksi HTTPS ke server gagal total di tingkat jabat tangan SSL/TLS. Klien melihat kesalahan SSL_ERROR_NO_CYPHER_OVERLAP dan log Caddy mencatat:

Error: TLS handshake error from 203.0.113.1:12345: tls: no certificate available

Penyebab Utama #

Caddy menerima permintaan jabat tangan TLS untuk domain tertentu (lewat identifikasi SNI), namun Caddy tidak memiliki sertifikat yang cocok di penyimpanan lokalnya untuk domain tersebut. Hal ini terjadi jika domain tersebut baru saja ditambahkan dan proses penerbitan sertifikat belum selesai, atau Caddy dikonfigurasi untuk memblokir penerbitan otomatis untuk domain tersebut (misal tidak terdaftar di Named Matcher).

Langkah Diagnosis & Solusi #

Pastikan sertifikat telah berhasil diterbitkan dan disimpan dengan benar:

# 1. Periksa folder penyimpanan lokal sertifikat Caddy
# Untuk deployment systemd standar, letaknya ada di /var/lib/caddy/
sudo ls -la /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/

# 2. Cek apakah sertifikat domain Anda ada di dalam daftar di atas.
# Jika tidak ada, periksa log inisialisasi awal Caddy untuk melihat mengapa proses ACME tertunda:
sudo journalctl -u caddy -b | grep -E "obtaining|certificate|ACME"

# 3. Skenario sertifikat kedaluwarsa atau corrupt
# Jika file sertifikat rusak, Anda dapat memindahkannya ke folder cadangan dan memaksa Caddy meminta ulang:
sudo mv /var/lib/caddy/.local/share/caddy/certificates/acme-v02.api.letsencrypt.org-directory/example.com /tmp/example.com-backup
sudo systemctl reload caddy

8. Too Many Redirects (ERR_TOO_MANY_REDIRECTS) #

Gejala Kesalahan #

Browser memunculkan layar kesalahan pengalihan terlalu banyak (infinite redirect loops) saat kita mencoba memuat situs web.

Penyebab Utama #

Caddy secara default mengalihkan (redirect) semua lalu lintas HTTP (port 80) ke HTTPS (port 443). Jika Caddy berada di belakang CDN atau Load Balancer (seperti Cloudflare, AWS ALB, atau F5 BIG-IP) yang melakukan terminasi SSL di tingkat edge dan meneruskan koneksi kembali ke Caddy dalam bentuk HTTP biasa (port 80), maka:

CDN menerima HTTPS, lalu meneruskan HTTP ke Caddy.
Caddy melihat HTTP, lalu merespons dengan perintah redirect ke HTTPS.
CDN menerima redirect tersebut, mengirimkannya kembali ke browser klien, dan siklus berulang tanpa henti.

Langkah Diagnosis & Solusi #

Kita harus memberi tahu Caddy untuk mempercayai header protokol asli yang dikirim oleh CDN/Load Balancer menggunakan konfigurasi trusted_proxies:

# Uji jalur pengalihan secara detail menggunakan curl
curl -L -v https://example.com 2>&1 | grep -E "Location:|< HTTP"
# Jika Anda melihat baris Location bolak-balik HTTPS-HTTP-HTTPS, loop terjadi.

# Solusi: Daftarkan IP Load Balancer Anda di opsi global Caddyfile
{
    servers {
        trusted_proxies static 10.0.0.0/8 192.168.1.0/24  # Ganti dengan CIDR IP Load Balancer Anda
    }
}

example.com {
    # Dengan trusted_proxies aktif, Caddy akan mengenali header X-Forwarded-Proto
    # dan tidak akan melakukan redirect HTTP jika klien asli sebenarnya menggunakan HTTPS
    reverse_proxy localhost:3000
}

9. WebSocket Connection Failed #

Gejala Kesalahan #

Aplikasi web yang mengandalkan koneksi real-time (seperti Socket.io, Chat, atau dashboard) gagal memuat fitur interaktif. Browser memunculkan kesalahan di konsol pengembang:

WebSocket connection to 'wss://example.com/socket.io/' failed: Unexpected response code: 400

Penyebab Utama #

Protokol WebSocket memerlukan mekanisme jabat tangan khusus (Connection Upgrade) dari HTTP/1.1 ke WebSocket. Pada server web tradisional seperti Nginx, kita harus mengonfigurasi header Upgrade dan Connection secara manual. Di Caddy, penanganan upgrade ini sebenarnya sudah otomatis dilakukan secara bawaan. Namun, kegagalan bisa terjadi jika backend kita menolak nilai header tertentu yang diubah oleh gateway, atau karena koneksi diputus secara sepihak oleh aturan timeout jaringan.

Langkah Diagnosis & Solusi #

Lakukan pengujian jabat tangan WebSocket secara manual untuk mendeteksi respons backend:

# 1. Kirim request upgrade WebSocket buatan menggunakan curl
curl -i -N \
    -H "Connection: Upgrade" \
    -H "Upgrade: websocket" \
    -H "Host: example.com" \
    -H "Origin: https://example.com" \
    -H "Sec-WebSocket-Key: SGVsbG8sIHdvcmxkIQ==" \
    -H "Sec-WebSocket-Version: 13" \
    https://example.com/socket.io/

# Hasil yang benar (Status 101 Switching Protocols):
# HTTP/1.1 101 Switching Protocols
# Upgrade: websocket
# Connection: Upgrade

Jika mengembalikan status 400 atau 404, periksa apakah backend Anda memang mendengarkan koneksi WebSocket di jalur URL tersebut. Di Caddyfile, pastikan kita mematikan kompresi jika itu mengganggu transmisi paket WebSocket:

example.com {
    # Jika aplikasi WebSocket Anda bermasalah dengan kompresi,
    # kecualikan jalur WebSocket dari kompresi encode global
    encode gzip zstd
    
    reverse_proxy localhost:3000 {
        # websocket handshake diteruskan secara otomatis oleh Caddy
    }
}

10. Rate Limit Terkena Terus (False Positive 429) #

Gejala Kesalahan #

Klien tepercaya atau bahkan pengembang internal tiba-tiba terblokir dengan status respons 429 Too Many Requests.

Penyebab Utama #

Kita mengonfigurasi modul caddy-ratelimit menggunakan kunci pendeteksi {remote_host}. Namun, karena gateway Caddy berada di belakang proxy/load balancer eksternal dan kita belum mendaftarkan IP proxy tersebut di opsi global trusted_proxies, Caddy mengidentifikasi IP load balancer tersebut sebagai alamat IP klien tunggal. Akibatnya, seluruh lalu lintas global dihitung sebagai request dari satu pengguna dan langsung memicu pemblokiran.

Langkah Diagnosis & Solusi #

Pastikan deteksi alamat IP publik klien asli berjalan dengan benar di Caddy:

# 1. Jalankan curl dan periksa header X-RateLimit jika ada
curl -I https://api.example.com/

# 2. Periksa access log Caddy untuk melihat apakah IP klien dicatat sebagai IP lokal proxy
# Jika log menunjukkan IP seperti 10.0.x.x atau 172.x.x.x alih-alih IP publik klien,
# berarti Anda mengalami miskonfigurasi IP asal.

# Perbaikan Caddyfile:
{
    servers {
        # Aktifkan pelacakan IP klien melalui proxy tepercaya
        trusted_proxies static 10.0.0.0/8
    }
}

api.example.com {
    @trusted_devs remote_ip 203.0.113.50  # IP publik developer
    
    rate_limit {
        zone general_api {
            key {remote_host}  # Sekarang mengidentifikasi IP publik klien asli berkat trusted_proxies
            window 1m
            events 60
            exclude @trusted_devs  # Lewatkan limitasi untuk developer
        }
    }
    
    reverse_proxy localhost:3000
}

11. Caddy Tidak Bisa Menulis Sertifikat (Permission Denied) #

Gejala Kesalahan #

Proses penerbitan sertifikat SSL macet total, dan ketika memeriksa log kita melihat pesan izin ditolak (permission denied):

Error: open /var/lib/caddy/.local/share/caddy/certificates/...: permission denied

Penyebab Utama #

Direktori penyimpanan data sertifikat Caddy (/var/lib/caddy/ atau /var/lib/caddy/.local/) memiliki kepemilikan (ownership) atau hak akses berkas (file permission) yang salah. Ini biasanya terjadi ketika kita pernah menjalankan Caddy sekali waktu menggunakan perintah sudo caddy run sebagai user root, sehingga sistem membuat folder sertifikat baru dengan pemilik root, yang kemudian tidak bisa diakses kembali oleh pengguna sistem biasa caddy saat dijalankan via systemd.

Langkah Diagnosis & Solusi #

Kembalikan hak akses kepemilikan folder data Caddy ke user sistem caddy:

# 1. Periksa kepemilikan direktori storage Caddy
ls -la /var/lib/caddy/
# Jika pemiliknya adalah root:root, perbaiki segera.

# 2. Kembalikan kepemilikan secara rekursif ke user dan group caddy
sudo chown -R caddy:caddy /var/lib/caddy/

# 3. Setel izin direktori agar aman (hanya pemilik yang memiliki akses penuh)
sudo chmod -R 750 /var/lib/caddy/

# 4. Uji kemampuan menulis folder menggunakan identitas user caddy
sudo -u caddy touch /var/lib/caddy/.local/share/caddy/test-permission && echo "Izin Menulis: OK"

# 5. Bersihkan berkas uji coba dan restart Caddy
sudo -u caddy rm /var/lib/caddy/.local/share/caddy/test-permission
sudo systemctl restart caddy

12. Caddy Tiba-tiba Berhenti (OOM Killer) #

Gejala Kesalahan #

Server Caddy mati mendadak tanpa ada catatan kesalahan apa pun di log akhir Caddy. Ketika memeriksa status layanan, kita melihat status Killed atau Main process exited, code=killed, status=9/KILL.

Penyebab Utama #

Proses Caddy dihentikan paksa oleh fitur internal kernel Linux bernama OOM (Out Of Memory) Killer. Hal ini terjadi ketika server kehabisan memori RAM fisik dan memori swap akibat beban koneksi yang sangat tinggi, adanya memory leak pada modul plugin kustom, atau karena ada aplikasi backend di server yang sama yang memakan seluruh kapasitas RAM.

Langkah Diagnosis & Solusi #

Lacak catatan peristiwa kernel untuk memverifikasi apakah pembunuhan paksa memori memang terjadi:

# 1. Periksa log dmesg sistem untuk mendeteksi OOM
sudo dmesg -T | grep -i -E "oom|killed"
# Output contoh: Out of memory: Killed process 5678 (caddy) total-vm:4194304kB, anon-rss:2097152kB

# 2. Periksa log sistem umum
sudo journalctl -k | grep -i -E "oom|killed"

# 3. Solusi Jangka Pendek: Konfigurasikan Systemd agar me-restart Caddy otomatis jika crash
sudo systemctl edit caddy

Tambahkan blok konfigurasi override berikut di editor Systemd:

[Service]
# Paksa Systemd me-restart Caddy jika mati tidak wajar
Restart=on-failure
# Tunggu 5 detik sebelum mencoba restart
RestartSec=5s
# Batasi upaya restart otomatis agar tidak loop tiada henti jika kerusakan permanen
StartLimitIntervalSec=300
StartLimitBurst=5

13. Sertifikat Let’s Encrypt Rate Limit Terlampaui #

Gejala Kesalahan #

Saat menambahkan banyak subdomain sekaligus untuk pertama kali di server baru, Caddy tiba-tiba memunculkan pesan kesalahan limitasi laju ACME:

Error: rateLimited: too many certificates already issued for exact set of domains: ...

Penyebab Utama #

Let’s Encrypt menerapkan batas laju (rate limits) yang ketat untuk melindungi infrastruktur mereka. Batas paling umum adalah 50 sertifikat baru per domain induk per minggu. Jika kita berulang kali menghapus dan membuat kontainer Docker Caddy atau berulang kali me-reload konfigurasi dengan perubahan nama domain kecil saat melakukan eksperimen, kita akan dengan cepat melampaui batas ini.

Langkah Diagnosis & Solusi #

Gunakan lingkungan pengujian (staging) selama fase uji coba konfigurasi sebelum beralih ke sertifikat produksi:

# Perbaikan Caddyfile untuk fase testing / eksperimen:
{
    # Menggunakan endpoint staging Let's Encrypt (tidak memiliki batasan laju seketat produksi)
    acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

test.example.com {
    file_server
}

# Lacak riwayat sertifikat yang telah diterbitkan untuk domain Anda secara publik
curl -s "https://crt.sh/?q=example.com&output=json" | \
    jq '[.[] | select(.not_before > (now - 604800 | todate))] | length'
# Output menunjukkan berapa banyak sertifikat yang diterbitkan dalam 7 hari terakhir.

Jika Anda sudah terlanjur terkena rate limit, kita bisa mengakali ini sementara dengan mengubah otoritas penerbit (CA Issuer) ke ZeroSSL yang tidak menggunakan batasan laju Let’s Encrypt:

# Beralih ke ZeroSSL ACME Directory
{
    acme_ca https://acme.zerossl.com/v2/DV90
}

14. Memory Usage Terus Meningkat #

Gejala Kesalahan #

Server Caddy mengalami peningkatan penggunaan RAM secara konstan (gradual memory growth) selama berhari-hari tanpa pernah turun kembali ke level normal, bahkan setelah jam sibuk berakhir.

Penyebab Utama #

Kebocoran memori (memory leak) biasanya disebabkan oleh plugin atau modul pihak ketiga (seperti plugin third-party logging, custom auth, atau L4 proxy kustom) yang tidak mengelola alokasi memori Go secara bersih. Pada core engine Caddy sendiri, kebocoran memori sangat jarang terjadi.

Langkah Diagnosis & Solusi #

Kita perlu memantau penggunaan memori secara berkala dan mengisolasi penyebabnya:

# 1. Pantau konsumsi memori RSS (Resident Set Size) proses Caddy secara real-time
watch -n 10 'ps aux | grep caddy | grep -v grep | awk "{print \$6/1024 \" MB - RAM Usage\"}"'

# 2. Lacak apakah ada kebocoran file descriptor yang menahan alokasi memori
sudo lsof -p $(pgrep caddy) | wc -l

# 3. Solusi Isolasi:
# Jika Anda mencurigai plugin tertentu sebagai biang keladi, kompilasi ulang biner Caddy
# tanpa plugin tersebut secara bertahap untuk memverifikasi apakah konsumsi RAM menjadi stabil.

Sebagai workaround sementara di lingkungan produksi selagi melakukan debugging kode plugin, Anda dapat menjadwalkan proses pemuatan ulang konfigurasi (graceful reload) melalui cron harian. Berbeda dengan server web lain, caddy reload membersihkan alokasi memori runtime lama secara aman (atomic swap) tanpa memutus koneksi klien yang sedang aktif:

# Tambahkan di crontab root untuk reload anggun setiap jam 4 pagi
0 4 * * * /usr/bin/caddy reload --config /etc/caddy/Caddyfile > /dev/null

Ringkasan #

Port Binding Conflict — Kesalahan address already in use diselesaikan dengan melacak proses yang menduduki port menggunakan sudo lsof -i :80,443 lalu mematikan proses tersebut.
Port Privileged — Menjalankan Caddy sebagai non-root pada port 80/443 memerlukan pemberian kapabilitas kernel via sudo setcap cap_net_bind_service=+ep $(which caddy).
Tantangan ACME — Kegagalan sertifikat SSL/TLS tantangan HTTP-01 sering kali karena port 80 terblokir firewall atau karena DNS record domain belum mengarah ke IP server.
502 Bad Gateway — Menandakan Caddy kehilangan koneksi ke backend hilir. Pastikan service backend hidup dan dengarkan di port yang sesuai.
Loop Redirect — Terjadi akibat bentrokan HTTPS termination antara CDN/load balancer dan Caddy. Atasi dengan mendaftarkan IP load balancer pada blok trusted_proxies.
Atomic Config Swap — Caddy mendukung reload tanpa downtime. Lakukan validasi defensif terlebih dahulu menggunakan perintah caddy validate sebelum mengaplikasikannya di produksi.

← Sebelumnya: API Gateway Berikutnya: Debug Config →