Setelah mendeploy beberapa aplikasi Rails dengan Kamal, saya mulai merasakan gesekannya. Setiap kali saya ingin mengecek apakah aplikasi saya online, saya harus SSH ke server atau menjalankan kamal app details untuk setiap proyek. Kalau mau deploy artinya saya mesti pindah direktori, jalankan command, pantau log. Mau toggle maintenance mode? Lebih banyak lagi juggling di terminal.

Tulisan ini juga tersedia dalam bahasa Inggris.

Lalu saya melihat demo oleh DHH tentang ONCE, bagaimana pendekatan 37signals untuk self-hosted web apps dengan dashboard terpadu. Namun demikian, saya kurang tertarik untuk mengkonversi semua proyek saya menjadi aplikasi yang didukung ONCE, tapi idenya cukup stuck di kepala saya: bagaimana kalau saya bisa punya tampilan single-pane-of-glass untuk semua deployment Kamal saya sendiri?

Oleh karena itu saya membuat HQ.

Apa itu HQ?

HQ adalah dashboard berbasis terminal (TUI) untuk memantau dan mengelola proyek yang dideploy dengan Kamal. Ini adalah aplikasi Ruby satu file yang memberikan pandangan menyeluruh dari semua deployment kamu di satu tempat.

Anggap saja seperti mission control untuk armada Kamal kamu.

HQ Dashboard menampilkan beberapa aplikasi dengan status health, action yang berjalan, dan panel detail

Fitur

Berikut yang bisa kamu lakukan dari HQ:

  • Health monitoring: Lihat sekilas aplikasi mana yang sehat, tidak sehat, atau dalam maintenance mode. Simpel aja, cuma ngecek dengan curl.
  • Version tracking: Menampilkan versi Kamal dan Rails, dengan versi yang outdated ditandai warna oranye
  • Panel detail: Pilih aplikasi apapun untuk melihat konfigurasi lengkapnya: image, hosts, proxy, healthcheck path
  • One-key deploy: Tekan d untuk deploy proyek yang dipilih (dengan konfirmasi)
  • Toggle maintenance: Tekan m untuk mengaktifkan atau menonaktifkan maintenance mode
  • Action logs: Tekan l untuk melihat log deployment dan action
  • Health logs: Tekan h untuk melihat riwayat health check
  • Auto-refresh: Health check berjalan otomatis setiap 30 detik
  • Background actions: Deploy berjalan di background dan tetap jalan meski HQ di-_restart_
  • Pengelompokan server: Aplikasi dikelompokkan berdasarkan IP host untuk kemudahan scanning

Screenshot di atas menunjukkan bagaimana HQ beraksi: lima aplikasi di tiga server, dengan dua action berjalan bersamaan (yang satu deploying, satunya lagi live), satu aplikasi dalam maintenance mode, dan panel detail menampilkan konfigurasi lengkap untuk aplikasi yang dipilih.

Stack yang Digunakan

Saya memilih membangun HQ dengan Bubbletea, Lipgloss, dan Bubbles: port Ruby dari library Go Charm. Kalau kamu pernah melihat aplikasi terminal modern seperti lazygit atau k9s, kamu sudah melihat apa yang bisa dilakukan ekosistem Charm.

Aplikasi ini mengikuti Elm Architecture (Model-View-Update):

class HQ
  def init
    # Inisialisasi state
  end

  def update(message)
    # Handle input, update state
  end

  def view
    # Render UI
  end
end

Pattern ini membuat aplikasi surprisingly maintainable meskipun hanya satu file. Perubahan state eksplisit, dan UI adalah pure function dari state tersebut.

Cara Kerjanya

HQ membaca konfigurasi proyek Kamal secara langsung. Arahkan ke direktori yang berisi config/deploy.yml, dan dia mengekstrak:

  • Nama service dan Docker image
  • Server hosts
  • Konfigurasi proxy dan healthcheck path
  • Versi Kamal dan Rails (dari Gemfile.lock)
  • Hash commit terbaru

Health check menggunakan request HEAD (bukan GET) karena kamal-proxy mengembalikan status 503 yang benar untuk maintenance mode hanya pada request HEAD. Sebuah gotcha yang saya pelajari the hard way.

Ketika kamu memicu action seperti deploy, HQ membuat proses terpisah yang menjalankan bin/kamal deploy di direktori proyek. Proses ini dimonitor dan output-nya ditangkap ke file log. Karena terpisah, kamu bisa keluar dari HQ dan kembali nanti: deploy kamu tetap berjalan.

Mengapa TUI?

Saya bisa saja membuat web dashboard. Tapi saya menghabiskan sebagian besar waktu di terminal anyway. TUI berarti:

  • Tidak ada browser tab yang perlu dikelola
  • Tidak ada server yang perlu dijalankan
  • Startup instan
  • Bisa diakses lewat SSH
  • Kelihatan keren (jujur, demikian adanya)

Color scheme Dracula juga nambahin cream at the top.

Cara Memulai

bundle install
ruby hq.rb

Keybindings:

  • j/k untuk navigasi
  • r untuk refresh health
  • d untuk deploy
  • m untuk toggle maintenance
  • l untuk melihat log
  • q untuk keluar

Apa Selanjutnya

HQ ini adalah tools yang masih orok banget. Beberapa ide yang sedang saya eksplorasi:

  • Dukungan multiple server per proyek
  • Fungsionalitas rollback
  • Integrasi dengan layanan error tracking
  • Health check server remote (bukan hanya kamal-proxy)

Giliran Kamu

Mengelola banyak aplikasi personal adalah masalah yang menyenangkan untuk dimiliki. Itu berarti kamu shipping, tak hanya building. Kendala bermunculan setelah kamu mulai mengelola proyek ketiga atau keempat.

HQ adalah jawaban saya: satu file Ruby yang memberi saya bird-eye-view ke semuanya. Belum publik, tapi saya ingin berbagi di sini karena saya penasaran bagaimana orang lain menyelesaikan masalah ini.

Apakah kamu punya setup atau automation serupa? Dashboard atau script? Saya ingin tahu bagaimana kamu mengelola armada web app kamu.