Ubuntu / Debian

Instalasi di Ubuntu / Debian #

Ubuntu dan Debian adalah sistem operasi paling umum untuk deployment server di cloud dan VPS. Caddy menyediakan repository APT resmi yang dikelola dengan baik, sehingga instalasi dan upgrade bisa dilakukan sepenuhnya melalui package manager standar. Ini berarti Caddy terintegrasi dengan baik ke dalam workflow manajemen paket yang sudah ada — apt upgrade biasa sudah cukup untuk mendapatkan versi terbaru.

Artikel ini mencakup seluruh proses dari instalasi hingga konfigurasi awal yang benar, termasuk detail tentang permission, systemd service, dan troubleshooting masalah yang paling umum terjadi.

Prasyarat #

Sebelum memulai, pastikan sistem memenuhi syarat berikut:

# Cek versi Ubuntu/Debian yang digunakan
lsb_release -a

# Pastikan package list terbaru
sudo apt update

# Pastikan curl tersedia
which curl || sudo apt install -y curl

Caddy mendukung Ubuntu 20.04, 22.04, 24.04 LTS, dan Debian 11 (Bullseye), 12 (Bookworm). Untuk versi yang lebih lama, instalasi via binary manual (tanpa APT) masih dimungkinkan.

Instalasi via Repository APT Resmi #

Cara yang direkomendasikan adalah menggunakan repository APT resmi yang dihosting oleh Cloudsmith (hosting partner resmi Caddy). Repository ini menyediakan binary yang sudah di-sign secara kriptografis untuk memastikan keasliannya.

# Step 1: Install dependencies yang diperlukan untuk menambahkan repository HTTPS
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl

# Step 2: Tambahkan GPG key repository Caddy ke sistem
# GPG key ini digunakan untuk memverifikasi bahwa package yang diunduh
# benar-benar dari tim Caddy dan tidak dimodifikasi
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg

# Step 3: Tambahkan entri repository ke sources list APT
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list

# Step 4: Update daftar package dan install Caddy
sudo apt update
sudo apt install caddy

Setelah instalasi selesai, verifikasi bahwa Caddy terinstall dengan benar:

# Cek versi Caddy
caddy version
# Contoh output: v2.8.4 h1:XYZ123abc...

# Cek apakah systemd service sudah terdaftar
sudo systemctl status caddy

# Cek apakah binary ada di PATH
which caddy
# Output: /usr/bin/caddy

Struktur File Setelah Instalasi #

Instalasi via APT membuat semua file dan direktori yang diperlukan secara otomatis:

/usr/bin/caddy                     ← Binary Caddy
                                     Ini adalah executable utama

/etc/caddy/                        ← Direktori konfigurasi
│   Caddy membaca konfigurasi dari sini saat dijalankan via systemd
│
└── Caddyfile                      ← File konfigurasi utama
                                     Edit file ini untuk mengatur Caddy

/var/lib/caddy/                    ← Direktori data Caddy
│   JANGAN dihapus — berisi data penting
│
└── .local/share/caddy/            ← Sertifikat TLS dan data ACME
                                     Let's Encrypt certificates disimpan di sini

/var/log/caddy/                    ← Direktori log
│
└── (kosong — log ditulis via systemd journal secara default)
    (akses via: sudo journalctl -u caddy)

/lib/systemd/system/caddy.service  ← Unit file systemd
                                     Mendefinisikan bagaimana Caddy dijalankan
                                     sebagai system service

/etc/apt/sources.list.d/           ← Repository APT
└── caddy-stable.list              ← Entry repository Caddy

/usr/share/keyrings/               ← GPG keys
└── caddy-stable-archive-keyring.gpg ← GPG key untuk verifikasi package

User dan Group Caddy #

Instalasi APT secara otomatis membuat user sistem khusus bernama caddy dengan group caddy. Caddy berjalan sebagai user ini — bukan sebagai root — yang merupakan praktik keamanan yang baik.

# Lihat informasi user caddy
id caddy
# Output: uid=999(caddy) gid=999(caddy) groups=999(caddy)

# Cek ownership direktori
ls -la /etc/caddy/
ls -la /var/lib/caddy/
ls -la /var/log/caddy/

Mengelola Caddy dengan Systemd #

Instalasi via APT secara otomatis membuat dan mengaktifkan systemd service. Caddy sudah dikonfigurasi untuk start otomatis saat server boot.

Perintah Systemd Dasar #

# Cek status Caddy secara lengkap
sudo systemctl status caddy

# Output yang diharapkan saat Caddy berjalan:
# ● caddy.service - Caddy
#      Loaded: loaded (/lib/systemd/system/caddy.service; enabled; ...)
#      Active: active (running) since ...
#    Main PID: 1234 (caddy)
#       Tasks: 9
#      Memory: 45.2M
#         CPU: 2.154s
#      CGroup: /system.slice/caddy.service
#              └─1234 /usr/bin/caddy run --environ ...

# Start Caddy (jika belum berjalan)
sudo systemctl start caddy

# Stop Caddy
sudo systemctl stop caddy

# Enable — pastikan Caddy start otomatis saat boot
sudo systemctl enable caddy

# Disable — jangan start otomatis saat boot
sudo systemctl disable caddy

Reload vs Restart — Perbedaan yang Penting #

Ini adalah perbedaan yang sangat penting untuk deployment production:

# CARA YANG BENAR: Reload konfigurasi TANPA downtime
# Caddy membaca Caddyfile baru dan menerapkannya secara graceful
# Koneksi yang sedang berjalan tidak diputus
# Request baru langsung menggunakan konfigurasi baru
sudo systemctl reload caddy

# CARA YANG KURANG IDEAL: Restart Caddy
# Ada downtime singkat (~100ms-1s) karena Caddy benar-benar berhenti
# lalu start ulang — semua koneksi aktif diputus
# Hindari untuk production kecuali benar-benar diperlukan
sudo systemctl restart caddy
Selalu gunakan sudo systemctl reload caddy untuk menerapkan perubahan konfigurasi di production. Reload menerapkan konfigurasi baru secara graceful menggunakan SIGHUP signal tanpa memutus koneksi yang sedang berjalan. Gunakan restart hanya jika ada masalah yang tidak bisa diselesaikan dengan reload.

Melihat Log Systemd #

# Log terbaru (tail 50 baris)
sudo journalctl -u caddy -n 50

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

# Log dengan timestamp lengkap
sudo journalctl -u caddy --output=short-precise

# Log hanya error dan warning
sudo journalctl -u caddy -p warning

# Log dari waktu tertentu
sudo journalctl -u caddy --since "2024-01-01 00:00:00"
sudo journalctl -u caddy --since "1 hour ago"

# Export log ke file untuk analisis
sudo journalctl -u caddy --since "today" > /tmp/caddy-today.log

Konfigurasi Awal #

Edit Caddyfile #

# Buka editor untuk mengedit konfigurasi
sudo nano /etc/caddy/Caddyfile
# atau
sudo vim /etc/caddy/Caddyfile

Caddyfile Default Setelah Instalasi #

APT menginstall Caddyfile default yang menyajikan halaman welcome di semua interface:

# Caddyfile default — hapus dan ganti dengan konfigurasi kamu
# The Caddyfile is an easy way to configure your Caddy web server.
# https://caddyserver.com/caddyfile
#
# A Caddyfile has at minimum a key (which is a site address) and values
# which are directives. Read the documentation for directive syntax:
# https://caddyserver.com/caddyfile/directives

:80 {
    # Set this path to your site's directory.
    root * /usr/share/caddy

    # Enable the static file server.
    file_server

    # Another common task is to set up a reverse proxy:
    # reverse_proxy localhost:8080

    # Or serve a PHP site through php-fpm:
    # php_fastcgi localhost:9000
}

Konfigurasi untuk Domain Nyata #

Ganti isi Caddyfile dengan konfigurasi yang sesuai kebutuhanmu:

# Contoh 1: Static website sederhana
example.com {
    root * /var/www/html
    file_server
}

# Contoh 2: Reverse proxy ke aplikasi di port 3000
example.com {
    reverse_proxy localhost:3000
}

# Contoh 3: Multiple domain
app.example.com {
    reverse_proxy localhost:3000
}

api.example.com {
    reverse_proxy localhost:8080
}

# Contoh 4: Redirect www ke non-www
www.example.com {
    redir https://example.com{uri} permanent
}

example.com {
    root * /var/www/html
    file_server
}

Validasi Konfigurasi Sebelum Reload #

Ini adalah langkah yang wajib dilakukan sebelum reload di production. Jika Caddyfile mengandung syntax error, systemd reload akan gagal dan konfigurasi lama tetap berjalan. Lebih baik mengetahui error sebelum reload.

# Validasi konfigurasi — tidak perlu sudo
caddy validate --config /etc/caddy/Caddyfile

# Jika valid, output:
# Valid configuration

# Jika ada error, output menunjukkan letak error:
# Error: adapting config using caddyfile: ...
# Parsing caddyfile tokens for 'example.com' block:
#   /etc/caddy/Caddyfile:5 - missing closing brace

# Workflow yang direkomendasikan:
caddy validate --config /etc/caddy/Caddyfile && sudo systemctl reload caddy

Port 80 dan 443 — Permission #

Di Linux, proses non-root tidak bisa bind ke port di bawah 1024 secara default. Instalasi via APT mengatasi ini melalui Linux capabilities yang dikonfigurasi di unit file systemd.

Cara Instalasi APT Menanganinya #

# Lihat unit file systemd Caddy
cat /lib/systemd/system/caddy.service

# Bagian yang relevan:
# [Service]
# ...
# AmbientCapabilities=CAP_NET_BIND_SERVICE
# CapabilityBoundingSet=CAP_NET_BIND_SERVICE

# CAP_NET_BIND_SERVICE memberikan hak untuk bind ke port < 1024
# tanpa perlu menjalankan proses sebagai root

Ini berarti Caddy berjalan sebagai user caddy (non-root) tapi tetap bisa listen di port 80 dan 443 — setup keamanan yang ideal.

Jika Kamu Menjalankan Caddy Manual (Bukan via Systemd) #

Jika kamu menjalankan caddy run langsung di terminal sebagai user biasa, kamu perlu memberikan capability secara manual:

# Berikan permission CAP_NET_BIND_SERVICE ke binary Caddy
sudo setcap cap_net_bind_service=+ep /usr/bin/caddy

# Verifikasi capability sudah di-set
getcap /usr/bin/caddy
# Output: /usr/bin/caddy cap_net_bind_service=ep

# Sekarang kamu bisa menjalankan caddy sebagai user biasa
# dan dia bisa bind ke port 80/443
caddy run --config /etc/caddy/Caddyfile
Perlu dicatat bahwa setiap kali kamu mengupgrade atau mengganti binary Caddy, capability yang di-set via setcap akan hilang dan perlu di-set ulang. Ini adalah salah satu alasan mengapa menjalankan Caddy via systemd (yang menangani ini otomatis) lebih disarankan.

DNS dan Firewall #

Sebelum Caddy bisa mendapatkan sertifikat HTTPS, pastikan:

DNS Sudah Diarahkan ke Server #

# Cek apakah domain sudah mengarah ke IP server kamu
dig +short example.com
nslookup example.com

# IP yang dikembalikan harus cocok dengan IP server kamu
curl ifconfig.me  # Cek IP publik server

Firewall Mengizinkan Port 80 dan 443 #

# Ubuntu menggunakan ufw (Uncomplicated Firewall)
# Cek status firewall
sudo ufw status

# Izinkan HTTP dan HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp  # Untuk HTTP/3

# Atau gunakan profile yang sudah ada
sudo ufw allow 'WWW Full'

# Reload firewall
sudo ufw reload

# Verifikasi
sudo ufw status verbose

Upgrade Caddy #

Karena Caddy diinstall via APT repository resmi, upgrade semudah menjalankan perintah update biasa:

# Update daftar package
sudo apt update

# Cek versi yang tersedia
apt-cache policy caddy

# Upgrade Caddy saja
sudo apt upgrade caddy

# Atau upgrade semua package termasuk Caddy
sudo apt upgrade

# Verifikasi versi setelah upgrade
caddy version

# Systemd service otomatis restart setelah upgrade package
sudo systemctl status caddy

Setelah upgrade, Caddy secara otomatis di-restart oleh APT. Jika kamu ingin zero-downtime upgrade, perlu menggunakan metode yang berbeda (stop service, ganti binary, start service) — tapi untuk sebagian besar deployment, downtime singkat saat upgrade tidak menjadi masalah.

Menyesuaikan Systemd Unit File #

Jika kamu perlu mengkustomisasi cara Caddy dijalankan oleh systemd (misalnya menambahkan environment variable atau mengubah working directory), jangan edit /lib/systemd/system/caddy.service langsung karena file ini akan di-overwrite saat upgrade.

Gunakan systemd override:

# Buat override file
sudo systemctl edit caddy

# Editor akan terbuka — tambahkan kustomisasi di sini
# Misalnya untuk menambahkan environment variable:
[Service]
Environment="DOMAIN=example.com"
Environment="[email protected]"

# Simpan dan keluar
# Systemd otomatis reload configuration

# Verifikasi konfigurasi efektif
sudo systemctl cat caddy

Kemudian di Caddyfile kamu bisa menggunakan environment variable:

{env.DOMAIN} {
    reverse_proxy localhost:3000
}

Uninstall #

# Hapus Caddy tapi simpan konfigurasi dan data
sudo apt remove caddy

# Hapus semua termasuk konfigurasi di /etc/caddy
sudo apt purge caddy

# Hapus repository (opsional, untuk pembersihan total)
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 dan sertifikat (HATI-HATI — tidak bisa di-recover)
sudo rm -rf /var/lib/caddy
sudo rm -rf /var/log/caddy

sudo apt purge caddy akan menghapus direktori /etc/caddy/ termasuk Caddyfile kamu. Backup konfigurasi sebelum melakukan purge jika kamu ingin menyimpannya:

sudo cp /etc/caddy/Caddyfile ~/Caddyfile.backup

Troubleshooting Masalah Umum #

Caddy Gagal Start — Port Sudah Digunakan #

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

# Temukan proses yang menggunakan port 80 atau 443
sudo ss -tlnp | grep ':80\|:443'
sudo lsof -i :80
sudo lsof -i :443

# Contoh: Apache atau Nginx sudah berjalan
sudo systemctl stop apache2
sudo systemctl stop nginx

# Atau jika tidak butuh lagi, disable juga
sudo systemctl disable apache2

Caddy Tidak Bisa Mendapatkan Sertifikat #

# Cek log untuk error ACME
sudo journalctl -u caddy -n 100 | grep -i "error\|acme\|certificate"

# Kemungkinan penyebab:
# 1. DNS belum propagate ke IP server ini
dig +short example.com  # Harus return IP server kamu

# 2. Port 80 tidak bisa diakses dari internet
# (diblokir cloud provider security group / firewall)
sudo ufw status
# Cek juga security group di AWS/GCP/DigitalOcean panel

# 3. Caddy sedang di-rate limit oleh Let's Encrypt
# Tunggu beberapa jam atau cek logs untuk pesan rate limit

Permission Denied pada File atau Direktori #

# Jika Caddy tidak bisa baca webroot kamu
sudo chown -R caddy:caddy /var/www/html
sudo chmod -R 755 /var/www/html

# Atau berikan read permission untuk semua user
sudo chmod -R o+r /var/www/html

# Cek permission yang ada
ls -la /var/www/html

Konfigurasi Tidak Berlaku Setelah Reload #

# Pastikan validasi berhasil dulu
caddy validate --config /etc/caddy/Caddyfile

# Jika valid, force reload
sudo systemctl reload caddy

# Verifikasi konfigurasi aktif via Admin API
curl http://localhost:2019/config/ | jq .apps.http

# Jika masih tidak berlaku, coba restart penuh
sudo systemctl restart caddy
sudo journalctl -u caddy -f

Ringkasan #

  • Gunakan repository APT resmi (Cloudsmith) untuk instalasi yang terintegrasi dengan package management Ubuntu/Debian dan mendapat update otomatis.
  • File konfigurasi utama ada di /etc/caddy/Caddyfile — user caddy harus bisa membacanya.
  • Data dan sertifikat di /var/lib/caddy/ — jangan hapus direktori ini.
  • Selalu gunakan systemctl reload caddy untuk menerapkan perubahan — bukan restart — untuk menghindari downtime.
  • Wajib jalankan caddy validate sebelum reload di production untuk mencegah konfigurasi rusak menggantikan konfigurasi yang berfungsi.
  • Caddy berjalan sebagai user caddy non-root tapi bisa bind port 80/443 via CAP_NET_BIND_SERVICE capability yang dikonfigurasi di systemd.
  • Untuk troubleshooting, sudo journalctl -u caddy -f adalah teman terbaik kamu.

← Sebelumnya: Arsitektur Caddy   Berikutnya: CentOS / RHEL →

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