LDAPWeb/AI-Agent-Standards/templates/repo/guide/migration.md

Migration Guide — Server & Domain

Owner: checklist migrasi server/domain, urutan cutover, verifikasi, rollback. Inventori host: ../server.md. Requirement tool: ../system-requirements.md. Template env: ../../.env.example (root project).

Prinsip: URL/domain dynamic — ubah .env / config, bukan source code (kecuali refactor env var baru).

---

Kapan pakai guide ini

• Migrasi app/service ke server baru (IP/host berubah)
• Ganti domain (mis. old.example.com -> new.example.com)
• Pindah database ke host/instance baru
• Cutover staging -> prod dengan URL baru

---

Inventori sebelum migrasi

Item	Nilai saat ini	Nilai target	File yang harus diupdate
Domain / base URL			.env.example, .env (lokal), server.md
API base URL			kode baca env saja
DB host			.env.example, server.md
Reverse proxy			nginx/IIS config path di repo
SSL / cert
DNS record			catatan di server.md

---

Variabel env yang terpengaruh

Salin dari .env.example, isi kolom old/new:

Variabel	Old	New	Sudah di .env prod?
API_BASE_URL
APP_URL
DB_HOST
{CUSTOM}

Commit yang boleh: .env.example, docs — jangan commit .env berisi secret.

---

Langkah migrasi (server)

1. Persiapan

   • Backup data & config server lama
   • Server baru memenuhi system-requirements.md
   • Install runtime/stack (Docker, nginx, DB, dll.) di server baru
   • Siapkan .env di server baru dari .env.example

2. Deploy ke server baru (parallel)

   • Deploy kode/config ke server baru
   • Point .env ke dependency internal (DB, Redis, dll.)
   • Smoke test internal (IP/host langsung, belum DNS publik)

3. Cutover

   • Update DNS / firewall / load balancer
   • Update reverse proxy (nginx/IIS) ke backend baru
   • Update .env production dengan URL/host final
   • Restart service / container

4. Verifikasi

   • Health check endpoint
   • Login / auth flow
   • Integrasi ke project monorepo lain (jika ada)
   • Client app (APK/web) masih pakai env — rebuild hanya jika BuildConfig berubah

5. Dokumentasi (wajib)

   • Update ../server.md (host, URL, mapping path)
   • Update .env.example jika nama variabel/placeholder berubah
   • Append entri migrasi di ../version.md + ../changelog.md
   • Overwrite ../ai-session-summary.md (Tier 1 handover)

---

Langkah migrasi (domain saja, server sama)

1. Tambah DNS / cert untuk domain baru
2. Update reverse proxy server_name / binding
3. Ubah .env: API_BASE_URL, APP_URL, CORS_ORIGIN, dll.
4. Redirect domain lama -> baru (opsional, periode transisi)
5. Update docs: server.md, .env.example
6. Smoke test dari client dengan URL baru

Tidak perlu ubah kode jika semua URL sudah dari env.

---

Android / mobile (Kotlin Agent dll.)

Area	Saat migrasi domain
Base URL API	gradle.properties / BuildConfig / flavor — bukan hardcode di .kt
Network security	network_security_config.xml jika domain/cert berubah
Release	Rebuild APK jika BuildConfig berubah; OTA channel sesuai [release guide]

---

Rollback

1. Kembalikan DNS / proxy ke server/domain lama
2. Restore .env backup
3. Restart service
4. Catat rollback di ../issues.md + session summary

---

Riwayat migrasi

Tanggal	Dari	Ke	Session / versi	Catatan
{YYYY-MM-DD}	{old host/domain}	{new}	{session-id}