HTTPS Otomatis Caddy: Cara Kerja Auto TLS Caddy dan Solusi Masalahnya

Singkatnya: Caddy mengaktifkan HTTPS secara otomatis untuk setiap alamat situs yang berupa nama domain publik. Caddy meminta sertifikat melalui ACME (secara default Let's Encrypt atau ZeroSSL), membuktikan kendali atas domain lewat challenge HTTP-01 atau TLS-ALPN-01 di port 80 dan 443, mengalihkan HTTP ke HTTPS, dan memperbarui sertifikat sebelum kedaluwarsa, tanpa konfigurasi tambahan.

Reverse proxy Caddy sebenarnya hanyalah Caddy yang mengakhiri koneksi HTTPS tersebut lalu meneruskan request ke aplikasi di port, container, atau host lain menggunakan directive `reverse_proxy`. Kombinasi itu, TLS plus proxy dalam beberapa baris, adalah alasan utama orang memilihnya.

Reverse proxy dengan SSL dalam tiga baris

Dengan DNS mengarah ke server dan port 80 serta 443 dapat dijangkau, Caddyfile ini sudah merupakan reverse proxy HTTPS lengkap untuk dua hostname. Caddy memperoleh sertifikat untuk kedua nama saat startup, melayani HTTP/1.1, HTTP/2, dan HTTP/3, serta meneruskan `X-Forwarded-For`, `X-Forwarded-Proto`, dan `X-Forwarded-Host` ke backend. Opsi `email` bersifat opsional, tetapi memungkinkan CA menghubungi Anda soal sertifikat yang akan kedaluwarsa atau dicabut.

Instalasi dari repositori apt resmi dan dasar-dasar systemd dibahas di panduan reverse proxy Caddy; untuk container, lihat Caddy sebagai reverse proxy Docker. Terapkan perubahan dengan `sudo systemctl reload caddy`.

# /etc/caddy/Caddyfile
{
	email [email protected]
}

example.com, www.example.com {
	reverse_proxy 127.0.0.1:8080
}

Cara kerja auto TLS Caddy di balik layar

Saat Caddy memuat konfigurasi, ia mengumpulkan setiap hostname dari alamat situs dan menentukan siapa yang harus menerbitkan masing-masing sertifikat. Domain publik ditangani penerbit ACME publik; `localhost`, alamat IP, dan nama khusus internal mendapat sertifikat dari CA lokal milik Caddy sendiri (sama seperti menulis `tls internal`). Sertifikat, kunci, dan akun ACME disimpan di direktori data Caddy: `/var/lib/caddy/.local/share/caddy` untuk paket apt, `/data` di image Docker resmi.

Pembaruan berlangsung di latar belakang jauh sebelum kedaluwarsa, dan Caddy melakukan OCSP stapling jika CA mendukungnya. Jika penerbitan gagal, Caddy mencoba ulang dengan exponential backoff dan memakai endpoint staging CA untuk percobaan ulang agar tidak menghabiskan rate limit produksi. Beberapa instance Caddy yang berbagi storage yang sama saling berkoordinasi sehingga hanya satu yang meminta sertifikat tertentu.

Sertifikat wildcard dengan DNS-01

Sertifikat wildcard seperti `*.example.com` hanya dapat diterbitkan melalui challenge DNS-01. Binary Caddy standar tidak menyertakan plugin penyedia DNS, jadi Anda membuatnya dengan xcaddy (atau memilih penyedia di halaman unduhan resmi) dan memberi Caddy token API yang dibatasi hanya untuk mengedit DNS zona tersebut. DNS-01 juga berfungsi saat port 80 dan 443 tidak dapat dijangkau dari internet, misalnya pada server khusus internal.

Jangan taruh token di Caddyfile: simpan di file environment yang dipakai unit systemd (`sudo systemctl edit caddy`, lalu `EnvironmentFile=/etc/caddy/caddy.env` di bawah `[Service]`) dan batasi aksesnya dengan `chmod 600`.

# Build Caddy with a DNS provider module (example: Cloudflare)
xcaddy build --with github.com/caddy-dns/cloudflare

# Caddyfile: one wildcard certificate for all subdomains
*.example.com {
	tls {
		dns cloudflare {env.CF_API_TOKEN}
	}

	@app host app.example.com
	handle @app {
		reverse_proxy 127.0.0.1:3000
	}

	handle {
		respond "Unknown host" 404
	}
}

On-demand TLS dan staging

On-demand TLS membuat Caddy memperoleh sertifikat saat TLS handshake pertama untuk hostname yang belum pernah dilihatnya. Fitur ini ditujukan untuk platform tempat pelanggan mengarahkan domain mereka sendiri ke server Anda. Selalu konfigurasikan endpoint `ask`: Caddy memanggilnya dengan `?domain=name` dan hanya melanjutkan jika responsnya 200. Tanpanya, siapa pun bisa mengarahkan nama acak ke IP Anda dan membuat Anda terkena rate limit.

Saat bereksperimen, beralihlah ke CA staging Let's Encrypt dengan opsi global `acme_ca`. Sertifikat staging tidak dipercaya browser, tetapi limitnya jauh lebih tinggi, sehingga Anda bebas merusak dan memperbaiki konfigurasi. Hapus opsi tersebut, dan jika perlu hapus sertifikat staging dari direktori data, setelah selesai.

{
	on_demand_tls {
		ask http://127.0.0.1:5555/allowed
	}
}

https:// {
	tls {
		on_demand
	}
	reverse_proxy 127.0.0.1:8080
}

# Global options block for testing
{
	email [email protected]
	# Test against Let's Encrypt staging; remove when everything works
	acme_ca https://acme-staging-v02.api.letsencrypt.org/directory
}

Kegagalan TLS Caddy yang umum dan cara memperbaikinya

1. 01.DNS belum diarahkan: record A atau AAAA tidak ada, masih mengarah ke server lama, atau masih ter-cache. Record AAAA usang adalah jebakan klasik, karena CA lebih memilih IPv6 jika tersedia. Periksa keduanya dengan `dig`.
2. 02.Port 80 atau 443 tertutup: firewall host, firewall cloud, atau router memblokir trafik masuk, sehingga HTTP-01 maupun TLS-ALPN-01 tidak bisa selesai. Buka 80/tcp dan 443/tcp (serta 443/udp untuk HTTP/3).
3. 03.Port sudah dipakai: Apache, nginx, atau container lain terikat ke 80 atau 443, sehingga Caddy tidak bisa listen. Hentikan layanan lain itu atau pindahkan ke belakang Caddy.
4. 04.Proxy CDN di depan: proxy ala "awan oranye" mengakhiri TLS sebelum Caddy, yang bisa merusak TLS-ALPN-01. Gunakan DNS-01, atau set record ke DNS-only selama penerbitan.
5. 05.Rate limit: percobaan gagal berulang atau menghapus direktori data membuat Anda terkena limit CA (Let's Encrypt membatasi validasi gagal per hostname per jam dan sertifikat duplikat per minggu). Perbaiki akar masalahnya, gunakan staging, dan jaga direktori data tetap persisten.
6. 06.Record CAA: record CAA yang hanya mengizinkan CA lain akan memblokir penerbitan. Izinkan `letsencrypt.org` dan `sectigo.com` (dipakai oleh ZeroSSL) atau hapus pembatasannya.

# Does the name resolve to this server (both IPv4 and IPv6)?
dig +short A example.com
dig +short AAAA example.com
curl -4 -s https://ifconfig.me ; echo

# Are ports 80 and 443 open in the host firewall?
sudo ufw status
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp

# Is something else already bound to 80/443?
sudo ss -ltnp '( sport = :80 or sport = :443 )'

# What does Caddy say?
sudo journalctl -u caddy --no-pager -n 100

HTTPS ke backend juga

Sebagian besar backend di host yang sama berbicara HTTP biasa di localhost, dan itu tidak masalah. Jika upstream berada di mesin lain atau mewajibkan TLS, gunakan upstream `https://` dan beri tahu Caddy nama mana yang harus diverifikasi dan CA mana yang dipercaya. Hindari `tls_insecure_skip_verify` di luar pengujian singkat, karena opsi itu menghilangkan perlindungan terhadap penyadapan antara proxy dan backend. Untuk trafik antarserver, tunnel WireGuard privat sering lebih sederhana daripada mengelola sertifikat backend.

Di VPS NoctisNode dengan root penuh dan alamat IPv4 dedicated, pengaturan umumnya: arahkan record A (tanpa AAAA kecuali server punya IPv6) ke server, buka port 80 dan 443, dan biarkan Caddy menangani sisanya. Jika Anda perlu meneruskan trafik non-HTTP, lihat proxy TCP dan SSH dengan Caddy.

example.com {
	reverse_proxy https://10.0.0.5:8443 {
		transport http {
			tls_server_name backend.internal
			tls_trust_pool file /etc/caddy/backend-ca.pem
		}
	}
}

FAQ