Cara Deploy ke VPS dengan Kamal (Panduan Lengkap)

Kamal tidak berjalan di VPS Anda. Ia adalah alat deployment yang Anda pasang di mesin sendiri atau di runner CI, dan ia terhubung ke server lewat SSH untuk bekerja. Basecamp membuatnya untuk merilis aplikasi Rails tanpa Kubernetes, tetapi Kamal men-deploy apa saja yang bisa dibangun menjadi image Docker.

Perbedaan itu mengubah apa yang sebenarnya Anda cari. VPS adalah target Kamal, jadi ia harus cukup besar untuk aplikasi Anda, basis datanya, dan beberapa hari versi image. Jejak Kamal sendiri di server adalah nol.

Apa yang Sebenarnya Ditaruh Kamal di Server

kamal setup terhubung lewat SSH (sebagai root secara bawaan, diautentikasi dengan kunci SSH Anda) dan menjalankan tiga langkah: memasang Docker kalau belum ada, menjalankan aksesori yang Anda deklarasikan, lalu men-deploy aplikasi. Setelah itu host menjalankan:

• kamal-proxy — proxy HTTP kecil yang memegang port 80 dan 443, mengambil sertifikat Let’s Encrypt, dan menahan permintaan masuk selama deploy sampai kontainer penggantinya siap.
• Kontainer aplikasi Anda — satu set untuk tiap peran yang didefinisikan di config/deploy.yml.
• Aksesori — Postgres, Redis, atau layanan lain yang Anda daftarkan di konfigurasi.

Kamal sendiri adalah sebuah gem (gem install kamal, versi 2.12.0 saat tulisan ini dibuat) dan tidak meninggalkan daemon apa pun.

Prasyarat

Sebelum mulai, siapkan:

• VPS dengan instalasi Linux bersih dan akses SSH root berbasis kunci (Ubuntu 24.04 adalah pilihan bawaan yang masuk akal)
• Registry kontainer yang bisa ditarik server Anda — Docker Hub, GitHub Container Registry, atau milik penyedia Anda
• Ruby di mesin lokal untuk gem install kamal; tanpa Ruby, Kamal bisa dijalankan dari image kontainer dengan beberapa keterbatasan
• Dockerfile yang berfungsi untuk aplikasi Anda

Memilih Penyedia VPS

Karena server hanya menjalankan kontainer, nilai penyedia dari keandalan jaringan, ruang disk, dan seberapa cepat Anda bisa membangun ulang sebuah host:

Untuk perbandingan menyeluruh, lihat halaman perbandingan VPS lengkap kami.

DigitalOcean adalah titik awal termudah di sini, karena dokumentasinya mencakup pekerjaan tingkat host yang tidak dikerjakan Kamal untuk Anda: aturan firewall, swap, dan pembaruan keamanan otomatis.

Menyiapkan Server

1. Buat VPS dengan image Ubuntu 24.04 minimal dan kunci SSH Anda terpasang.
2. Pastikan SSH root berfungsi, karena begitulah Kamal terhubung secara bawaan:

ssh root@ip-vps-anda

3. Buka hanya yang Anda perlukan. kamal-proxy mengakhiri TLS di server, jadi port 22, 80, dan 443 sudah cukup:

ufw allow 22,80,443/tcp && ufw enable

Anda tidak perlu memasang Docker sendiri. Kamal memasangnya pada kamal setup pertama kalau belum ada.

Memasang Kamal dan Menulis Konfigurasi

Di mesin Anda sendiri, di dalam direktori aplikasi:

gem install kamal
kamal init

kamal init membuat config/deploy.yml. Konfigurasi minimal yang berfungsi memerlukan nama layanan, sebuah image, dan setidaknya satu host:

service: myapp
image: pengguna-registry-anda/myapp

servers:
  web:
    hosts:
      - 203.0.113.10

registry:
  username: pengguna-registry-anda
  password:
    - KAMAL_REGISTRY_PASSWORD

proxy:
  ssl: true
  host: app.example.com

Rahasia disimpan di .kamal/secrets, yang dibaca Kamal saat deploy. Kamal mencari .kamal/secrets-common lebih dulu, baru .kamal/secrets:

KAMAL_REGISTRY_PASSWORD=$KAMAL_REGISTRY_PASSWORD

Jauhkan berkas itu dari kontrol versi dan ambil nilainya dari environment shell Anda atau dari pengelola kata sandi.

Menjalankan Deploy Pertama

kamal setup

Satu perintah itu memasang Docker, menjalankan aksesori, membangun dan mengirim image Anda, lalu menyalakan aplikasi. Setiap deploy berikutnya cukup:

kamal deploy

Untuk memeriksa apa yang berjalan di host:

kamal app containers

Di Mana Image Dibangun

Secara bawaan Kamal membangun image secara lokal, di mesin mana pun tempat Anda menjalankannya, lalu mengirimnya ke registry. Server hanya menarik. Kalau laptop Anda arm64 dan VPS-nya amd64, kunci arsitektur targetnya atau arahkan Kamal ke builder jarak jauh:

builder:
  arch: amd64
  remote: ssh://[email protected]

Cross-build lewat emulasi cukup lambat untuk terasa pada setiap deploy. Kalau VPS adalah satu-satunya mesin amd64 yang Anda punya, ia bisa merangkap sebagai builder — tetapi ukurlah untuk proses build Docker, bukan sekadar untuk menjalankan aplikasi, yang biasanya berarti naik satu paket demi RAM tambahan.

Mengukur Disk

Kamal menyimpan kontainer dan image lama di server supaya kamal rollback bisa menjalankan versi sebelumnya tanpa menarik ulang dari registry. Secara bawaan ia membersihkannya setelah tiga hari. Rencanakan ruang untuk data aplikasi Anda sendiri ditambah sekitar tiga hari versi image beserta lapisan dasar bersamanya.

Image 1 GB yang di-deploy beberapa kali sehari duduk nyaman di 40 GB NVMe milik Hetzner. Image 3 GB pada disk 25 GB akan memenuhinya dalam sepekan, dan disk penuh merusak deploy berikutnya, bukan yang sedang berjalan — yang membuatnya mudah terlewat sampai terlambat.

Peralihan Tanpa Downtime

kamal-proxy baru memindahkan trafik ke kontainer baru setelah kontainer itu menjawab GET /up dengan status 200. Dari sini ada dua konsekuensi:

• Aplikasi Anda perlu endpoint /up. Rails menyediakannya; framework lain biasanya butuh beberapa baris tambahan.
• Endpoint itu harus mengembalikan 200 hanya ketika aplikasi benar-benar bisa melayani permintaan. Kalau ia menjawab sebelum koneksi basis data siap, pengguna akan mengenai kontainer baru terlalu awal.

Kalau health check tidak pernah lolos, deploy kehabisan waktu dan Kamal membiarkan kontainer lama tetap melayani trafik.

Mengamankan Deployment

• Kamal terhubung sebagai root lewat SSH, jadi matikan autentikasi kata sandi sepenuhnya dan andalkan kunci.
• Biarkan kamal-proxy menangani TLS. Menambahkan reverse proxy kedua di depannya hanya merumitkan jalur sertifikat.
• Tambahkan swap pada host 4 GB. Deploy menjalankan kontainer lama dan baru bersamaan sesaat, dan host yang mulai melakukan swap di tengah deploy cukup lambat untuk memicu batas waktu health check.
• Simpan kata sandi registry di .kamal/secrets, bukan di config/deploy.yml yang ikut masuk kontrol versi.

Tips Penutup

• Jalankan kamal deploy dari CI setelah jalur manualnya berhasil. Konfigurasinya identik; yang berubah hanya sumber rahasianya.
• kamal rollback [versi] berlangsung seketika selama image lama masih ada di disk, jadi periksa kamal app containers sebelum menganggap target rollback-nya tersedia.
• Men-deploy aplikasi kedua ke host yang sama didukung di Kamal 2 — kamal-proxy merutekan berdasarkan hostname, jadi tiap aplikasi cukup punya nama service dan proxy.host sendiri.

Untuk pembahasan lebih lanjut soal memilih servernya, lihat halaman perbandingan VPS lengkap kami.