Runbook Konfigurasi dan Penyebaran

Pendahuluan

Runbook ini mendokumentasikan pengembangan lokal, build, runtime Docker, perilaku Nginx, konfigurasi runtime, dan langkah-langkah pemecahan masalah umum untuk frontend Ravenxcope.

---

Pengembangan Lokal

Instal dependensi menggunakan Yarn (direkomendasikan untuk konsistensi dengan Docker):

yarn install --frozen-lockfile

Perintah Umum:

• Dev Server: yarn dev
• Build: yarn build
• Lint: yarn lint

Perintah npm yang setara mungkin berfungsi secara lokal, tetapi build Docker produksi secara ketat menggunakan Yarn.

---

Variabel Lingkungan

Didokumentasikan dalam .env.example:

VITE_API_BASE_URL=
VITE_ANALYTICS_AI_CHAT_ENABLED=false

Variabel	Wajib	Default / Fallback	Tujuan
VITE_API_BASE_URL	Direkomendasikan	http://localhost:5009/api	URL basis backend
VITE_ANALYTICS_AI_CHAT_ENABLED	Tidak	false	Mengaktifkan UI chat AI analitik

Untuk produksi, tetapkan variabel-variabel ini pada kontainer agar docker-entrypoint.sh dapat menginjeksikannya.

---

Build Docker

Dockerfile menggunakan build dua tahap:

1. Tahap Builder:

   • Menggunakan node:22-alpine.
   • Menginstal dependensi dengan yarn install --frozen-lockfile.
   • Menghasilkan aset produksi dengan yarn build.

2. Tahap Runtime:

   • Menggunakan nginx:alpine.
   • Melayani aset dari /usr/share/nginx/html.
   • Menginjeksikan konfigurasi runtime melalui docker-entrypoint.sh.
   • Mengekspos port 8000.

---

Injeksi Konfigurasi Runtime

Saat startup kontainer, docker-entrypoint.sh menulis variabel ke dalam window.__APP_CONFIG__ sebelum memulai Nginx. Hal ini memungkinkan image yang sama disebarkan ke berbagai lingkungan (Staging, Produksi) tanpa harus melakukan build ulang.

---

Perilaku Nginx

nginx/default.conf mendengarkan pada port 8000 dan menyediakan:

• Penyajian Statis: Melayani aset yang dibangun dengan caching jangka panjang.
• Kompresi: Mengaktifkan gzip untuk aset teks dan JSON.
• Keamanan: Menambahkan X-Frame-Options, X-Content-Type-Options, dan X-XSS-Protection.
• Fallback SPA: Menggunakan try_files $uri $uri/ /index.html untuk mendukung perutean sisi klien.
• Kesegaran Konfigurasi: Melayani /config.js dengan header no-cache.

---

Daftar Periksa Penyebaran (Deployment Checklist)

Sebelum menyebarkan, verifikasi hal-hal berikut:

1. Keterjangkauan API: API Backend harus dapat dijangkau dari browser pengguna.
2. Origin API: VITE_API_BASE_URL harus berupa origin backend publik tanpa akhiran /api.
3. Status Chat: VITE_ANALYTICS_AI_CHAT_ENABLED=true memerlukan titik akhir chat backend yang terkonfigurasi.
4. Pemetaan Port: Port Nginx 8000 harus diarahkan dengan benar.
5. Verifikasi Konfigurasi: Pastikan /config.js mengembalikan nilai runtime yang diharapkan.
6. Fallback Rute: Pastikan rute dasbor dengan tautan dalam (deep-linked) disegarkan dengan benar.

---

Pemecahan Masalah

Permintaan login mengarah ke localhost

• Penyebab: VITE_API_BASE_URL hilang atau tidak valid.
• Pemeriksaan: Verifikasi konten /config.js. Harus berupa URL http atau https yang valid.

404 saat penyegaran dasbor

• Penyebab: Fallback SPA tidak aktif.
• Pemeriksaan: Pastikan nginx/default.conf terpasang dengan benar dan berisi direktif try_files.

Perubahan konfigurasi tidak tercermin

• Penyebab: Caching browser atau CDN pada /config.js.
• Pemeriksaan: Verifikasi header Cache-Control: no-store tersedia.

Auth mengalihkan ke login

• Kemungkinan Penyebab:
  • Cookie sesi hilang atau kadaluwarsa.
  • Backend mengembalikan 401.
  • Ketidakcocokan URL basis API.
  • Pembatasan kebijakan cookie SameSite.
• Pemeriksaan: Devtools browser untuk keberadaan cookie dan payload respons API.

Chat AI analitik hilang

• Kemungkinan Penyebab:
  • VITE_ANALYTICS_AI_CHAT_ENABLED bernilai false.
  • Titik akhir status chat backend tidak terjangkau atau melaporkan dinonaktifkan.
• Pemeriksaan: /config.js dan GET /api/analytics/chat/status.

---

Hal-hal yang Bukan Tujuan (Non-Goals)

Image frontend ini hanya melayani aplikasi browser dan konfigurasi runtime. Image ini tidak menjalankan layanan backend, database, atau agen sensor.