Deployment & Mitigasi Hosting

Panduan kanonis untuk memasang, memindahkan, dan memulihkan aplikasi di hosting baru. Tujuannya agar perpindahan provider (shared hosting, VPS, Hostinger, Rumahweb, atau lainnya) hanya menjadi perubahan infrastruktur dan tidak mengubah kontrak antara Laravel, database, portal web, dan aplikasi mobile.

Kasus referensi: login berhasil, tetapi santri/tagihan/transaksi tidak tampil

Login dan pengambilan data adalah request terpisah. Hosting dapat mengembalikan BIGINT/DECIMAL sebagai string JSON, misalnya "100000", atau data lama memiliki field opsional bernilai null. APK dengan cast ketat dapat gagal mem-parsing satu item lalu menyembunyikan seluruh daftar. Laravel Resources wajib menormalkan tipe; mobile tetap harus toleran terhadap angka/string dan field opsional.

Prinsip yang Tidak Boleh Berubah

  • API selalu berada di /api; endpoint wali berada di /api/wali/*.
  • Nilai uang, saldo, ID, dan persentase dikirim sebagai JSON number, bukan string.
  • Flag dikirim sebagai JSON boolean, bukan 0/1 atau string.
  • Field wajib tidak boleh null. Field opsional harus didokumentasikan dan parser mobile wajib memiliki fallback.
  • Relasi wali–santri disinkronkan dari No. KK saat login, tetapi penautan manual tetap dipertahankan.
  • Token API adalah Bearer token Sanctum; header Authorization harus diteruskan web server/proxy.
  • Gunakan HTTPS valid. APP_URL, URL webhook Midtrans, dan base URL mobile harus konsisten.

Checklist Sebelum Pindah Hosting

  1. Catat versi PHP, MySQL/MariaDB, Composer, dan ekstensi PHP aktif.
  2. Backup database, .env, storage/app, konfigurasi cron, queue, dan kredensial integrasi.
  3. Catat commit Git yang sedang produksi agar rollback dapat dilakukan tanpa menebak versi.
  4. Turunkan TTL DNS 24–48 jam sebelum cutover bila memungkinkan.
  5. Siapkan subdomain API stabil, misalnya api.example.id. Pindahkan DNS subdomain ini saat server berganti agar APK tidak perlu dibangun ulang hanya karena alamat origin berubah.
  6. Jangan menghapus hosting lama sebelum server baru stabil minimal 2–7 hari.

Instalasi Produksi di Server Baru

git checkout <commit-atau-tag-rilis>
composer install --no-dev --optimize-autoloader
npm ci
npm run build

php artisan migrate --force
php artisan storage:link
php artisan optimize:clear
php artisan config:cache
php artisan route:cache
php artisan view:cache

Jangan menyalin folder vendor dari komputer Windows/hosting lama. Build dependency pada environment tujuan. Pastikan document root mengarah ke folder public, bukan root repository.

Environment minimum produksi:

APP_ENV=production
APP_DEBUG=false
APP_URL=https://domain-produksi.example

DB_CONNECTION=mysql
DB_HOST=...
DB_PORT=3306
DB_DATABASE=...
DB_USERNAME=...
DB_PASSWORD=...

Cron, Queue, Storage, dan Midtrans

  • Scheduler: jalankan php artisan schedule:run setiap menit.
  • Queue VPS: gunakan Supervisor/systemd untuk php artisan queue:work.
  • Queue shared hosting: cron per menit dengan queue:work --stop-when-empty --max-time=45.
  • Pastikan storage dan bootstrap/cache dapat ditulis PHP.
  • Pastikan symlink public/storage tersedia; bila provider melarang symlink, ikuti mekanisme storage publik provider.
  • Ubah Payment Notification URL Midtrans menjadi https://domain-baru.example/midtrans/webhook dan uji webhook/sinkronisasi status.

Smoke Test Sebelum DNS Dipindahkan

Uji dengan domain sementara atau override hosts. Jangan hanya menguji login; login yang berhasil tidak membuktikan endpoint data berhasil.

  1. GET /api/wali/app-info — publik, harus JSON 200.
  2. POST /api/wali/login — simpan token dari respons.
  3. GET /api/wali/me dengan Bearer token.
  4. GET /api/wali/anak.
  5. GET /api/wali/anak/{id}/saldo.
  6. GET /api/wali/anak/{id}/tagihan.
  7. GET /api/wali/anak/{id}/transaksi.
  8. Uji top up sandbox, webhook Midtrans, unduh kwitansi, banner/logo, serta notifikasi queue.
  9. Uji wali tanpa anak, satu anak, dan beberapa anak dalam satu No. KK.
curl -H "Accept: application/json" \
  -H "Authorization: Bearer <token>" \
  https://domain-baru.example/api/wali/anak

curl -H "Accept: application/json" \
  -H "Authorization: Bearer <token>" \
  https://domain-baru.example/api/wali/anak/123/tagihan

Kontrak Tipe JSON yang Harus Diverifikasi

FieldTipe JSONContoh benarContoh salah
id, saldo, nominal, sisanumber100000"100000"
bisa_dicicil, biaya_ditanggung_waliboolean/null jika opsionalfalse"0"
metodestring"sistem"null
dataarray[]null
jatuh_tempo, foto_urlstring atau nullnullkey hilang tanpa dokumentasi

Sumber kebenaran kontrak ada di Laravel API Resources dan halaman Dokumentasi API Wali. Setiap perubahan bentuk JSON harus disertai test API dan parser mobile yang kompatibel mundur.

Diagnosis Cepat Berdasarkan Gejala

GejalaKemungkinanTindakan
Login gagal totalBase URL salah, SSL, kredensial, header/proxy, atau databaseUji app-info dan login dengan cURL; cek status HTTP.
Login berhasil, anak tidak tampilRelasi No. KK/pivot belum sinkron atau parsing field santri gagalCek /anak, tabel wali_santris, tipe saldo, dan log Laravel/mobile.
Anak tampil, tagihan/transaksi gagalBIGINT/DECIMAL menjadi string, field lama null, resource/controller tidak sama versiCek respons mentah endpoint terkait dan pastikan Resources terbaru terpasang.
401 setelah loginToken tidak terkirim/ability salah/cache konfigurasiPastikan header Bearer diteruskan dan route memakai auth:sanctum.
500Schema/migrasi tertinggal, permission, dependency, atau exception aplikasiCek storage/logs/laravel.log, php artisan migrate:status, dan permission.
Top up pending terusWebhook tidak sampai atau URL masih domain lamaPerbarui notification URL, cek signature/log, gunakan tombol sinkronisasi status.

Urutan Penanganan Insiden

  1. Catat waktu, akun uji, endpoint, status HTTP, dan response body; jangan hanya mengandalkan pesan UI.
  2. Cek storage/logs/laravel.log dan log web server pada waktu yang sama. Jangan mengirim token, password, atau Server Key ke chat/tiket.
  3. Bandingkan git rev-parse HEAD, composer.lock, php artisan migrate:status, PHP, dan database antara server lama/baru.
  4. Jalankan php artisan optimize:clear, lalu bangun ulang cache produksi.
  5. Perbaiki kontrak di Laravel Resource; jangan mengandalkan perilaku PDO provider tertentu.
  6. Tambahkan parser mobile toleran dan test regresi sebelum APK berikutnya.
  7. Jika dampaknya luas, rollback DNS/deployment ke commit dan database yang sudah diverifikasi.

Strategi Mobile Saat Domain Berubah

Build release dapat diarahkan tanpa mengedit source:

flutter build apk --release \
  --dart-define=API_BASE_URL=https://api.example.id/api

Domain API yang tetap lebih baik daripada membangun APK setiap kali hosting berganti. APK perlu dibangun ulang bila base URL di dalam build berubah, sertifikat/pinning berubah, atau ada perbaikan parser/fitur mobile. Perubahan backend yang mempertahankan domain dan kontrak API tidak memerlukan APK baru.

Checklist Setelah Cutover

  • HTTPS, redirect, login web seluruh role, login mobile, multi-anak, saldo, tagihan, transaksi, top up, pembayaran, dan kwitansi lulus.
  • Cron, queue, backup, restore uji, storage publik, email/push, dan webhook aktif.
  • Pantau 401/403/422/500, queue gagal, serta log Midtrans selama beberapa hari.
  • Simpan catatan tanggal cutover, commit, versi APK, versi PHP/database, dan hasil smoke test.