Instalasi di Ubuntu / Debian #

Ubuntu dan Debian merupakan sistem operasi berbasis Linux yang paling populer digunakan untuk pelayan (server) di infrastruktur cloud maupun Virtual Private Server (VPS). Caddy menyediakan repository APT resmi yang dipelihara secara aktif oleh tim core developer dan mitranya. Dengan memanfaatkan repository resmi ini, kita dapat memastikan bahwa proses instalasi, pembaruan (upgrade), dan pengelolaan sistem keamanan berjalan secara otomatis dan terintegrasi penuh dengan sistem manajemen paket bawaan sistem operasi.

Artikel ini akan membahas secara komprehensif langkah demi langkah instalasi Caddy pada Ubuntu dan Debian, mulai dari penyiapan repositori, pemahaman arsitektur direktori pasca-instalasi, konfigurasi systemd untuk operasi zero-downtime, hingga penanganan hak akses port rendah dan troubleshooting kasus produksi.

Prasyarat Sistem #

Sebelum kita memulai proses instalasi Caddy, kita harus memastikan bahwa sistem operasi kita berada dalam kondisi siap. Caddy mendukung arsitektur modern seperti amd64, arm64, dan armhf. Pastikan kita memiliki hak akses administratif (sudo) dan beberapa perkakas dasar telah terinstal di server kita.

Kita dapat melakukan verifikasi lingkungan server dengan perintah berikut:

# Memeriksa versi distribusi Ubuntu atau Debian yang kita gunakan
lsb_release -a

# Memastikan daftar paket repositori sistem operasi kita mutakhir
sudo apt update

# Memastikan curl dan gnupg terinstal untuk mengunduh kunci keamanan repositori
sudo apt install -y curl gnupg debian-keyring debian-archive-keyring apt-transport-https

Caddy mendukung secara resmi rilis Ubuntu LTS aktif (20.04, 22.04, 24.04 LTS) serta Debian Stable aktif (Debian 11 Bullseye dan Debian 12 Bookworm).

Instalasi via Repository APT Resmi #

Sangat tidak disarankan untuk mengunduh binary Caddy secara acak dari internet untuk server produksi kita. Metode terbaik dan paling aman adalah menggunakan repositori APT resmi yang di-host oleh Cloudsmith. Repositori ini menyediakan paket Debian (.deb) yang telah ditandatangani secara kriptografis menggunakan kunci GPG resmi untuk memastikan keaslian paket.

Berikut adalah urutan perintah untuk menambahkan repositori dan menginstal Caddy ke dalam sistem kita:

# Langkah 1: Unduh kunci GPG resmi Caddy dan simpan ke keyring sistem kita.
# Kunci ini memastikan sistem APT memvalidasi bahwa paket tidak dimodifikasi oleh pihak ketiga.
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Langkah 2: Tambahkan repositori Caddy ke daftar sumber APT (/etc/apt/sources.list.d/)
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Langkah 3: Perbarui basis data paket lokal kita agar membaca repositori yang baru ditambahkan
sudo apt update

# Langkah 4: Instal Caddy Web Server
sudo apt install -y caddy

Setelah instalasi selesai, kita dapat memverifikasi keberadaan Caddy dan status instalasinya:

# Memeriksa versi Caddy yang berhasil terpasang
caddy version
# Output yang diharapkan berupa informasi versi, commit hash, dan runtime Go, misalnya:
# v2.8.4 h1:XYZ123...

# Memeriksa lokasi executable Caddy
which caddy
# Output: /usr/bin/caddy

Struktur File Pasca-Instalasi #

Instalasi melalui paket manager APT secara otomatis menyusun direktori dan konfigurasi sistem sesuai dengan standar Filesystem Hierarchy Standard (FHS) pada Linux. Memahami letak file-file ini sangat krusial agar kita tidak melakukan kesalahan saat mengelola konfigurasi atau membackup sertifikat SSL.

Berikut adalah struktur direktori yang dibuat oleh installer APT Caddy:

/
├── usr/
│   └── bin/
│       └── caddy                      ← Binary utama Caddy (executable)
│
├── etc/
│   └── caddy/                         ← Direktori konfigurasi utama
│       └── Caddyfile                  ← File konfigurasi utama kita
│
├── var/
│   ├── lib/
│   │   └── caddy/                     ← Direktori data Caddy (Sangat Penting!)
│   │       └── .local/share/caddy/    ← Penyimpanan sertifikat TLS & kunci privat ACME
│   │
│   └── log/
│       └── caddy/                     ← Direktori log aplikasi (jika dikonfigurasi)
│
└── lib/
    └── systemd/
        └── system/
            └── caddy.service          ← File unit service systemd default

User dan Group Sistem caddy #

Installer APT secara otomatis membuat user sistem bernama caddy dan group caddy dengan hak akses terbatas (tidak memiliki shell interaktif dan tidak memiliki hak akses root).

# Memeriksa informasi user caddy yang dibuat otomatis
id caddy
# Output contoh: uid=998(caddy) gid=998(caddy) groups=998(caddy)

Untuk alasan keamanan, proses Caddy yang dikontrol oleh systemd akan dijalankan sebagai user caddy ini. Kita harus memastikan bahwa file-file situs web (misalnya file HTML atau PHP di /var/www/) dapat dibaca oleh user caddy agar server tidak menghasilkan error 403 Forbidden.

# Memastikan direktori data Caddy dimiliki oleh user caddy
ls -la /var/lib/caddy

Mengelola Caddy dengan Systemd #

Di lingkungan Ubuntu dan Debian, systemd bertindak sebagai manajer sistem dan layanan (service manager). Caddy yang terinstal melalui APT secara otomatis terdaftar sebagai unit service bernama caddy.service.

Perintah Layanan Dasar #

Kita dapat mengontrol siklus hidup layanan Caddy dengan perintah-perintah berikut:

# Memeriksa status detail layanan Caddy saat ini
sudo systemctl status caddy

# Mengaktifkan layanan Caddy agar berjalan otomatis saat server melakukan booting
sudo systemctl enable caddy

# Menjalankan layanan Caddy
sudo systemctl start caddy

# Menghentikan layanan Caddy
sudo systemctl stop caddy

Reload vs Restart: Kunci Menghindari Downtime di Produksi #

Salah satu keunggulan utama Caddy adalah kemampuannya memperbarui konfigurasi tanpa memutus koneksi klien yang sedang aktif. Kita harus memahami perbedaan mendasar kedua perintah ini:

# ANTI-PATTERN: Menghentikan total server lalu menjalankannya kembali.
# Koneksi klien aktif akan terputus seketika, menyebabkan downtime singkat.
sudo systemctl restart caddy

# BENAR: Menerapkan perubahan konfigurasi secara graceful.
# Caddy memvalidasi konfigurasi baru di memori, jika valid, ia menukar pointer 
# ke konfigurasi baru tanpa mematikan socket jaringan. Koneksi lama tetap dilayani 
# sampai selesai, koneksi baru langsung dilayani oleh konfigurasi baru. Zero downtime!
sudo systemctl reload caddy

Memantau Log Layanan via Journalctl #

Secara default, output standard (stdout/stderr) dari proses Caddy ditangkap oleh systemd journal. Kita dapat memantau aktivitas server, proses penerbitan sertifikat TLS, maupun error aplikasi menggunakan perintah journalctl:

# Memantau log Caddy secara real-time (seperti tail -f)
sudo journalctl -u caddy -f

# Memantau log Caddy dengan format timestamp presisi tinggi
sudo journalctl -u caddy -f --output=short-precise

# Menampilkan 100 baris log terakhir tanpa paginasi (cat)
sudo journalctl -u caddy -n 100 --no-pager

# Menampilkan log Caddy yang hanya berkategori Warning atau Error (pemberitahuan kritis)
sudo journalctl -u caddy -p err..warning --since "1 day ago"

Konfigurasi Awal dan Validasi Caddyfile #

Setelah terinstal, Caddy siap melayani request. File konfigurasi default kita berada di /etc/caddy/Caddyfile.

Konfigurasi Bawaan (Default Caddyfile) #

Secara default, installer menyertakan konfigurasi minimal yang melayani halaman sambutan Caddy pada port 80:

:80 {
    # Menentukan direktori dokumen situs web kita
    root * /usr/share/caddy

    # Mengaktifkan server file statis
    file_server
}

Konfigurasi untuk Domain Riil #

Jika kita ingin mengarahkan domain riil kita (misalnya situsku.com) dan mengaktifkan enkripsi HTTPS otomatis, kita cukup mengganti isi file konfigurasi tersebut:

# Mengedit file konfigurasi utama
sudo nano /etc/caddy/Caddyfile

Isi dengan konfigurasi sesuai kebutuhan arsitektur kita:

# Contoh 1: Menyajikan situs statis di domain riil dengan SSL otomatis
situsku.com {
    root * /var/www/situsku
    file_server
    encode gzip zstd
}

# Contoh 2: Bertindak sebagai reverse proxy untuk aplikasi Node.js yang berjalan di port 3000
app.situsku.com {
    reverse_proxy localhost:3000
}

# Contoh 3: Pengalihan (redirect) permanen dari www ke non-www
www.situsku.com {
    redir https://situsku.com{uri} permanent
}

Validasi Konfigurasi Sebelum Penerapan #

[!IMPORTANT] Selalu Validasi Sebelum Reload! Jangan pernah melakukan reload atau restart pada server produksi tanpa memvalidasi sintaksis Caddyfile terlebih dahulu. Jika terdapat kesalahan penulisan, perintah reload akan gagal, namun jika kita melakukan restart, server akan mati total dan tidak bisa dijalankan kembali hingga kesalahan diperbaiki.

Kita dapat memvalidasi integritas struktur Caddyfile kita menggunakan sub-perintah validate:

# Memvalidasi file konfigurasi secara lokal
caddy validate --config /etc/caddy/Caddyfile

Jika konfigurasi valid, kita akan melihat output: Valid configuration

Jika validasi berhasil, kita dapat melanjutkan dengan aman untuk memuat ulang konfigurasi:

# Alur kerja aman: lakukan validasi, jika sukses langsung jalankan reload
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

Hak Akses Port Rendah & Linux Capabilities #

Pada sistem operasi berbasis Linux, terdapat aturan keamanan ketat di mana proses non-root (seperti user caddy kita) tidak diizinkan untuk mengikat diri (bind) ke port istimewa di bawah 1024. Port 80 (HTTP) dan port 443 (HTTPS) berada dalam rentang port istimewa tersebut.

Bagaimana Systemd Menangani Hal Ini Secara Otomatis #

Installer APT Caddy menyelesaikan batasan ini dengan sangat elegan menggunakan Linux Capabilities tanpa perlu menjalankan proses server sebagai root (yang sangat berbahaya dari segi keamanan).

Jika kita memeriksa file unit systemd Caddy:

cat /lib/systemd/system/caddy.service

Kita akan menemukan deklarasi berikut di bawah bagian [Service]:

[Service]
...
User=caddy
Group=caddy
AmbientCapabilities=CAP_NET_BIND_SERVICE
CapabilityBoundingSet=CAP_NET_BIND_SERVICE
...

Instruksi CAP_NET_BIND_SERVICE memberikan hak khusus kepada binary /usr/bin/caddy untuk mengikat diri ke port 80 dan 443 meskipun ia berjalan di bawah identitas user non-root caddy.

Memberikan Hak Akses Manual (Jika Menjalankan Caddy Tanpa Systemd) #

Jika kita sedang melakukan debugging dan ingin menjalankan Caddy secara manual di terminal sebagai user biasa (bukan root) menggunakan perintah caddy run, kita akan menemui error Permission Denied saat mencoba mengikat port 80/443.

Untuk mengatasinya, kita dapat memberikan kemampuan (capability) tersebut secara manual ke file binary Caddy:

# Memberikan kemampuan CAP_NET_BIND_SERVICE secara persisten ke binary Caddy
sudo setcap cap_net_bind_service=+ep /usr/bin/caddy

# Memverifikasi apakah kemampuan telah berhasil dipasang
getcap /usr/bin/caddy
# Output: /usr/bin/caddy cap_net_bind_service=ep

Setelah kemampuan ini diberikan, kita dapat menjalankan Caddy sebagai user biasa di terminal dan ia tetap dapat mendengarkan lalu lintas pada port HTTP/HTTPS.

[!WARNING] Harap diingat bahwa setiap kali paket Caddy diperbarui (upgrade) via APT, file binary /usr/bin/caddy akan digantikan dengan binary baru yang bersih. Hal ini akan menghapus pengaturan setcap manual kita. Oleh karena itu, menjalankan Caddy di bawah kendali systemd adalah solusi terbaik karena systemd menerapkan kemampuan ini secara dinamis setiap kali proses dijalankan.

DNS dan Firewall (UFW) #

Caddy hanya dapat menerbitkan sertifikat SSL otomatis jika ia dapat menyelesaikan tantangan (challenge) ACME dari otoritas sertifikat (seperti Let’s Encrypt atau ZeroSSL). Hal ini membutuhkan dua prasyarat mutlak: DNS domain harus mengarah ke IP server kita, dan firewall tidak boleh menghalangi koneksi eksternal pada port HTTP/HTTPS.

1. Verifikasi DNS #

Pastikan domain kita telah dikonfigurasi dengan tipe A record yang mengarah ke alamat IP publik server kita. Kita dapat memverifikasinya dari dalam server menggunakan perkakas DNS:

# Menampilkan IP publik server kita
curl ifconfig.me
echo ""

# Memeriksa resolusi DNS domain kita
dig +short situsku.com
# Output harus mengembalikan IP publik yang sama dengan langkah pertama

2. Mengonfigurasi UFW (Uncomplicated Firewall) #

Ubuntu secara default menggunakan UFW sebagai antarmuka manajemen firewall. Kita harus membuka port 80 (TCP) dan port 443 (TCP & UDP) agar trafik internet dapat masuk. Caddy memanfaatkan port 443 UDP untuk mengaktifkan protokol HTTP/3 secara otomatis.

# Memeriksa status UFW saat ini
sudo ufw status

# Jika UFW aktif, izinkan lalu lintas web standar
# UFW menyediakan profil bawaan bernama 'WWW Full' yang membuka port 80 dan 443
sudo ufw allow 'WWW Full'

# Izinkan port 443 UDP secara eksplisit jika profil WWW Full tidak mencakup UDP (untuk HTTP/3)
sudo ufw allow 443/udp

# Memuat ulang aturan firewall
sudo ufw reload

# Memverifikasi bahwa port telah terbuka
sudo ufw status verbose

Modifikasi Unit Service Systemd dengan Override #

Jika kita perlu melakukan kustomisasi terhadap cara systemd menjalankan Caddy — misalnya menambahkan variabel lingkungan (environment variables), mengubah limitasi berkas terbuka (LimitNOFILE), atau menentukan direktori kerja kustom — kita tidak boleh mengedit berkas /lib/systemd/system/caddy.service secara langsung. Berkas tersebut akan ditimpa dan dikembalikan ke kondisi default saat kita melakukan pembaruan paket Caddy via APT.

Cara yang benar dan aman adalah menggunakan mekanisme systemd override.

# Membuka editor override systemd untuk caddy
sudo systemctl edit caddy

Perintah ini akan membuka editor teks kosong. Kita dapat menambahkan konfigurasi kustom kita di antara baris komentar yang disediakan. Sebagai contoh, mari tambahkan variabel lingkungan untuk kredensial domain atau email:

[Service]
Environment="DOMEN_UTAMA=situsku.com"
Environment="[email protected]"
LimitNOFILE=1048576

Simpan file tersebut dan keluar dari editor. Systemd akan secara otomatis membuat berkas override di /etc/systemd/system/caddy.service.d/override.conf dan memuat ulang konfigurasi daemon.

Kita dapat memverifikasi bahwa konfigurasi kustom telah digabungkan dengan benar:

# Menampilkan konfigurasi unit service yang aktif saat ini (termasuk override)
sudo systemctl cat caddy

Sekarang, kita dapat memanfaatkan variabel lingkungan tersebut di dalam /etc/caddy/Caddyfile kita:

{
    email {$EMAIL_ADMIN}
}

{$DOMEN_UTAMA} {
    reverse_proxy localhost:3000
}

Pemeliharaan dan Upgrade Caddy #

Karena kita menginstal Caddy melalui repositori APT resmi, pengelolaan pembaruan perangkat lunak menjadi sangat sederhana. Caddy akan masuk ke dalam siklus pembaruan rutin sistem operasi kita.

# Memperbarui daftar paket sistem
sudo apt update

# Memeriksa apakah ada versi baru Caddy yang tersedia di repositori
apt-cache policy caddy

# Mengupgrade Caddy saja tanpa menyentuh paket sistem lainnya
sudo apt install --only-upgrade caddy

# Atau melakukan pembaruan seluruh sistem secara berkala
sudo apt upgrade

Saat paket Caddy diperbarui via APT, sistem akan secara otomatis menghentikan proses lama secara aman, mengganti file binary, memuat ulang konfigurasi systemd, dan menjalankan kembali layanan Caddy secara otomatis.

Proses Penghapusan (Uninstall) #

Jika kita memutuskan untuk menghapus Caddy dari server kita, kita harus memahami perbedaan antara penghapusan biasa dan penghapusan total (purge) yang membersihkan seluruh sisa konfigurasi dan data sertifikat SSL.

# Metode 1: Hapus Caddy tetapi biarkan file konfigurasi dan data sertifikat tetap ada
sudo apt remove caddy

# Metode 2: Hapus Caddy dan seluruh file konfigurasi di /etc/caddy/
sudo apt purge caddy

# Langkah Pembersihan Tambahan (Opsional)
# Hapus repositori Caddy dari daftar APT agar sistem kita kembali bersih
sudo rm /etc/apt/sources.list.d/caddy-stable.list
sudo rm /usr/share/keyrings/caddy-stable-archive-keyring.gpg
sudo apt update

# Hapus data sertifikat SSL dan log (HATI-HATI: tindakan ini tidak dapat dibatalkan!)
# Lakukan ini hanya jika kita yakin tidak membutuhkan backup sertifikat TLS Let's Encrypt lagi.
sudo rm -rf /var/lib/caddy
sudo rm -rf /var/log/caddy

Troubleshooting Masalah Umum #

Saat menjalankan Caddy di Ubuntu/Debian, kita mungkin akan menemui beberapa kendala umum. Berikut adalah panduan langkah demi langkah untuk mendiagnosis dan menyelesaikannya.

1. Layanan Caddy Gagal Berjalan (Failed to Start) #

Jika status systemd menunjukkan status failed, langkah pertama kita adalah mencari kode kesalahan spesifik.

# Membaca log error startup terbaru
sudo journalctl -u caddy -n 50 --no-pager

Jika log menunjukkan pesan error seperti: listen tcp :80: bind: address already in use atau listen tcp :443: bind: address already in use

Artinya ada aplikasi lain (seperti Apache, Nginx, atau aplikasi backend kita sendiri) yang telah menduduki port 80 atau 443 sebelum Caddy berjalan. Kita dapat melacak aplikasi tersebut dengan perintah:

# Menemukan PID dan nama proses yang menduduki port 80 atau 443
sudo ss -tlnp | grep -E ':(80|443) '
# Atau menggunakan lsof
sudo lsof -i :80
sudo lsof -i :443

Jika aplikasi tersebut adalah Apache atau Nginx yang tidak kita butuhkan lagi, kita dapat mematikan dan menonaktifkannya dari startup:

# Menghentikan Apache
sudo systemctl stop apache2 && sudo systemctl disable apache2

# Menghentikan Nginx
sudo systemctl stop nginx && sudo systemctl disable nginx

# Jalankan kembali Caddy kita
sudo systemctl start caddy

2. Gagal Mendapatkan Sertifikat SSL (Akses HTTPS Warning) #

Jika situs web kita dapat diakses via HTTP (http://domain.com) tetapi memicu error keamanan saat diakses via HTTPS (https://domain.com), ini menandakan Caddy gagal menyelesaikan proses verifikasi kepemilikan domain (ACME challenge).

Lakukan pemeriksaan log transaksi ACME:

# Menyaring log yang berkaitan dengan kesalahan penerbitan sertifikat TLS
sudo journalctl -u caddy --since "1 hour ago" | grep -iE 'error|acme|certificate|challenge'

Beberapa penyebab umum kegagalan ini adalah:

  • Port 80/443 terblokir firewall: Let’s Encrypt wajib melakukan koneksi balik ke port 80 server kita untuk memverifikasi domain. Pastikan port 80 kita terbuka di UFW dan di panel kontrol penyedia cloud kita (seperti AWS Security Group atau DigitalOcean Firewall).
  • DNS belum menyebar (propagate): Jika domain baru saja dibeli atau diarahkan, tunggu beberapa waktu agar DNS terpropagasi sepenuhnya secara global sebelum memaksa Caddy meminta sertifikat.
  • Rate Limit Let’s Encrypt: Jika kita terlalu sering memicu error kegagalan validasi, Let’s Encrypt akan memblokir permintaan kita sementara. Kita dapat beralih ke ZeroSSL atau menunggu masa blokir selesai.

3. Masalah Hak Akses File (Permission Denied 403) #

Jika situs web statis kita menampilkan halaman error 403 Forbidden, ini menunjukkan proses Caddy tidak diizinkan membaca file di direktori webroot kita.

Karena Caddy berjalan sebagai user caddy, kita harus memberikan hak akses baca yang sesuai ke direktori situs web kita:

# Mengubah kepemilikan direktori webroot kita ke user dan group caddy
sudo chown -R caddy:caddy /var/www/situsku

# Memberikan hak akses baca & eksekusi yang aman (755 untuk direktori, 644 untuk berkas)
sudo find /var/www/situsku -type d -exec chmod 755 {} \;
sudo find /var/www/situsku -type f -exec chmod 644 {} \;

Kapan Beralih ke Alternatif / Tidak Menggunakan Ini #

Tetap gunakan instalasi APT jika:
  ✓ Server kita berupa VM/VPS tunggal berbasis Ubuntu atau Debian.
  ✓ Kita menginginkan proses pembaruan keamanan yang otomatis terintegrasi dengan OS.
  ✓ Konfigurasi kita standar dan hanya menggunakan modul bawaan Caddy.
  ✓ Kita menginginkan performa maksimal langsung di atas sistem (bare-metal) tanpa overhead container.

Pertimbangkan metode lain jika:
  ✗ Kita men-deploy aplikasi di lingkungan mikro (microservices) terdistribusi yang dikelola via Docker.
  ✗ Kita memerlukan modul DNS provider eksternal (seperti Cloudflare) untuk menerbitkan SSL Wildcard.
  ✗ Kebijakan organisasi mengharuskan isolasi aplikasi penuh menggunakan image container standar.

Ringkasan #

  • Repositori Resmi — Selalu gunakan repositori APT resmi Cloudsmith untuk memastikan paket Caddy kita asli, aman, dan mudah diperbarui.
  • Zero-Downtime — Gunakan perintah sudo systemctl reload caddy alih-alih restart untuk menerapkan perubahan konfigurasi tanpa mengganggu lalu lintas aktif klien.
  • Validasi Wajib — Biasakan menjalankan perintah caddy validate --config /etc/caddy/Caddyfile sebelum melakukan reload guna mencegah kegagalan runtime.
  • Hak Akses Port — Caddy berjalan aman sebagai user non-root caddy namun dapat mengikat port 80/443 berkat Linux Capabilities (CAP_NET_BIND_SERVICE) yang dipasang otomatis oleh systemd.
  • Persistensi TLS — Lokasi sertifikat TLS kita berada di /var/lib/caddy/.local/share/caddy/. Amankan dan jangan hapus direktori ini untuk menghindari limitasi batas permintaan Let’s Encrypt.
  • Manajemen Log — Gunakan perintah sudo journalctl -u caddy -f untuk memantau aktivitas server dan proses enkripsi SSL secara real-time.

← Sebelumnya: Instalasi   Berikutnya: CentOS / RHEL →

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