Panduan Penggunaan Launcher Go & Web Wizard Browser Lokal Dracin

Dokumen ini adalah panduan resmi (Single Source of Truth) untuk Launcher Go Single-Binary dan Wizard Browser Lokal Dracin. Panduan ini dirancang untuk seluruh pembeli maupun operator sistem.

---

1. Filosofi & Prinsip Desain

1. Zero-Friction & Self-Contained:
   • Pembeli tidak perlu memasang runtime eksternal apa pun di laptop lokal (tanpa Go, Node.js, PHP, Composer, Python, Docker, atau WSL).
   • Seluruh antarmuka web wizard (React SPA, styling Tailwind, font, ikon Lucide) dan resep deployment telah tertanam langsung ke dalam satu berkas binary executable (embed.FS).
2. Keamanan Tanpa Root/Admin di Laptop:
   • Launcher dapat dijalankan oleh user standar tanpa meminta hak akses Administrator (Windows) maupun sudo / root (macOS / Linux).
   • Hanya membuka port loopback dinamis (127.0.0.1:<port>), tidak pernah membuka koneksi publik 0.0.0.0.
   • Diproteksi secara kriptografis menggunakan token sesi acak 64-karakter hex. Permintaan tanpa token yang sah akan ditolak dengan 401 Unauthorized atau 403 Forbidden.
   • Log keluaran proses secara otomatis menyamarkan rahasia (secret auto-masking) seperti password SSH, token, dan APP_KEY.
3. Ramah Pengguna Awam (Zero-Friction):
   • Menghilangkan friksi terminal: browser terbuka secara otomatis ke alamat wizard.
   • Pesan kesalahan diterjemahkan menjadi bahasa yang jelas dan disertai petunjuk perbaikan yang konkret (actionable).
   • Menampilkan tombol "Buka Dracin" begitu proses selesai dan memberikan instruksi DNS A-record yang mudah dimengerti.

---

2. Cara Menjalankan Launcher

Menjalankan Langsung di Terminal / Konsol

# Menjalankan launcher (otomatis memilih port terbuka & membuka browser)
./dracin-launcher

# Atau jalankan tanpa membuka browser otomatis (mode headless/server)
./dracin-launcher --no-browser

# Menjalankan pada port tertentu
./dracin-launcher --port 28400

# Menentukan lokasi berkas konfigurasi .env.deploy khusus
./dracin-launcher --config /path/to/.env.deploy

Opsi Perintah Lengkap (--help)

Flag	Tipe	Default	Deskripsi
--port	integer	0 (otomatis)	Menentukan port loopback kustom (127.0.0.1)
--no-browser	boolean	false	Menonaktifkan pembukaan browser default secara otomatis
--config	string	.env.deploy	Lokasi berkas penyimpanan konfigurasi lokal
--repo-root	string	.	Lokasi root direktori repository aplikasi
--version	boolean	false	Menampilkan versi rilis launcher

---

3. Alur Wizard Web Langkah demi Langkah

Langkah 1: Kredensial Server VPS

• IP VPS / Hostname: Masukkan alamat IPv4 server (contoh: 167.86.108.118).
• Port SSH: Port SSH server Anda. Standar adalah 22, namun jika VPS menggunakan port kustom (seperti 20700), masukkan di kolom ini.
• SSH User: Gunakan user root atau user dengan hak akses sudo.
• Metode Autentikasi: Pilih antara Password atau SSH Private Key (berkas PEM / OpenSSH).
• Tombol "Uji Koneksi SSH Live":
  • Menguji konektivitas langsung ke VPS dan membaca OS, arsitektur, latensi jaringan, serta hak akses user.
  • Memberikan indikator hijau jika sukses atau kartu saran perbaikan jika gagal (misal: password salah atau port tertutup).

Langkah 2: Konfigurasi Aplikasi & Domain

• Domain Aplikasi: Masukkan domain yang Anda miliki (contoh: dracin.domainanda.com atau staging.dracin.test).
• Direktori Aplikasi: Lokasi instalasi di VPS (standar /var/www/dracin).
• Database SQLite Terintegrasi:
  • Dracin menggunakan SQLite berkinerja tinggi yang tersimpan aman di direktori persisten (shared/database/database.sqlite).
  • Zero-maintenance: tidak memerlukan konfigurasi server database terpisah seperti MySQL atau PostgreSQL.
  • Setiap pembaruan rilis secara otomatis mencadangkan (backup snapshot) database sebelum migrasi skema.
• Dracin Content API (Opsional): Kolom untuk mengisi URL API katalog konten dan API Key jika diperlukan.
• Simpan ke .env.deploy Lokal:
  • Opsi menyimpan konfigurasi di laptop pembeli agar tidak perlu mengetik ulang saat update di masa depan.
  • Berkas .env.deploy dibuat dengan hak akses terbatas (0600) dan diproteksi agar tidak pernah masuk ke Git (.gitignore).

Langkah 3: Eksekusi Deployment

Pilih jenis operasi:

1. Instalasi Baru (Fresh Install):
   • Menjalankan bootstrap Ubuntu 24.04 (memasang PHP 8.4 PPA, Nginx, modul-modul wajib, SQLite).
   • Menyiapkan struktur shared state persisten.
   • Mengunggah dan mengekstrak rilis awal (v1.0.0).
   • Menjalankan migrasi database dan automated health check HTTP.
2. Update Rilis Baru:
   • Mengunggah paket rilis versi terbaru (misal v2.0.0).
   • Melakukan backup database pre-migration secara otomatis.
   • Menjalankan migrasi skema Laravel dan beralih ke release baru (atomic zero-downtime switch).
   • Reload layanan PHP-FPM dan verifikasi health check.
3. Rollback Rilis:
   • Memindahkan symlink current kembali ke rilis sebelumnya secara instan jika rilis baru mengalami kendala.

Fitur Monitoring:

• Visual Step Tracker: Status 5 tahapan otomatis (Validasi → Bootstrap → Ekstraksi Paket → Migrasi → Health Check).
• Terminal Log Real-Time (SSE): Streaming baris keluaran server secara langsung dengan secret masking aktif.
• Actionable Error: Kartu solusi ramah awam jika terjadi kegagalan koneksi atau error server, dilengkapi tombol "Coba Lagi (Retry)".

Langkah 4: Selesai & Buka Dracin

• Tombol utama "Buka Dracin" langsung membuka aplikasi web di tab browser baru.
• Petunjuk DNS A-Record:
  • Panduan jelas untuk menambahkan A-Record di registrar domain pembeli (Cloudflare, Niagahoster, Namecheap, dll) yang mengarah ke IP VPS.
• Petunjuk SSL / HTTPS Gratis:
  • Petunjuk mengaktifkan SSL instan via Cloudflare Proxy atau Let's Encrypt Certbot.

---

4. Keamanan & Proteksi Secret

1. Auto-Masking Secret:
   • Mesin launcher memindai seluruh keluaran terminal remote dan mengganti teks sensitif dengan label [SECRET MASKED], [APP_KEY MASKED], [TOKEN MASKED], atau [PRIVATE KEY MASKED].
2. Penyimpanan .env.deploy:
   • Dibuat dengan izin berkas Unix 0600 (hanya dapat dibaca/ditulis oleh pemilik akun laptop).
   • Telah didaftarkan di .gitignore repositori sehingga tidak akan terunggah secara tidak sengaja.
3. Isolasi Loopback:
   • Permintaan HTTP yang berasal dari luar interface loopback lokal (127.0.0.1 / ::1) akan langsung ditolak dengan status HTTP 403 Forbidden.

---

5. Pemecahan Masalah (Troubleshooting)

Gejala	Kemungkinan Penyebab	Tindakan Solusi
401 Unauthorized di browser	Token sesi URL hilang atau tidak cocok	Muat ulang URL lengkap yang tercetak di terminal (yang menyertakan ?token=...).
Autentikasi SSH gagal	Password atau user salah	Periksa kembali password VPS Anda atau pastikan user root memiliki akses SSH aktif.
Koneksi SSH timeout / ditolak	Port SSH salah atau firewall aktif	Periksa apakah port SSH VPS menggunakan port non-standar (misal port 20700). Pastikan port terbuka di security group / firewall provider VPS.
Server bukan Ubuntu 24.04	Sistem operasi target tidak kompatibel	Gunakan VPS bersih dengan OS Ubuntu 24.04 LTS (Noble Numbat).
Health check HTTP gagal	Port 80 terblokir atau Nginx crash	Pastikan port 80/443 dibuka di firewall VPS dan domain mengarah ke server.

---

6. Verifikasi Otomatis

Untuk menguji seluruh komponen launcher dan wizard secara otomatis di lingkungan pengembangan:

./scripts/test-launcher.sh

Pengujian mencakup:

• Kompilasi single binary Go.
• Unit test Go untuk masker, auth loopback, env loader, dan tester SSH (mock server).
• Pengujian siklus hidup daemon HTTP pada loopback.
• Pengujian proteksi token sesi acak (penolakan HTTP 401).
• Pengujian integritas penyajian HTML wizard React tersemat (embed.FS).
• Pengujian koneksi diagnostik SSH live ke target staging VPS yang terotorisasi.