Instalasi & Kebutuhan Sistem

Akan memasang atau memindahkan server produksi?

Gunakan checklist lengkap pada halaman Deployment & Mitigasi Hosting. Halaman tersebut mencakup backup, DNS, kontrak JSON mobile, smoke test seluruh endpoint, diagnosis kasus login berhasil tetapi data gagal tampil, dan prosedur rollback.

Kebutuhan

Kebutuhan	Versi minimum
PHP	8.4.1+ (ekstensi: `pdo_mysql`, `mbstring`, `openssl`, `curl`, `zip`, `gd` atau `imagick` untuk foto santri)
Composer	2.x
Node.js & npm	Node 18+ (untuk build asset Vite/Tailwind)
MySQL	8.0+
Git	versi apa saja

Untuk produksi, jalankan scheduler php artisan schedule:run setiap menit dan worker queue sebagai proses tetap (php artisan queue:work, dikelola Supervisor/systemd). Pada shared hosting tanpa process manager, jalankan queue setiap menit dengan --stop-when-empty --max-time=45. Scheduler mengirim pengingat tagihan tiga hari sebelum jatuh tempo; queue memproses notifikasi tagihan baru. Gunakan domain HTTPS publik agar webhook Midtrans dapat diakses. Driver database cukup untuk instalasi awal; ketika jumlah pengguna/server bertambah, gunakan Redis untuk CACHE_STORE, SESSION_DRIVER, dan QUEUE_CONNECTION.

Langkah Instalasi (Development)

# 1. Clone & masuk folder proyek
git clone <url-repo> emall-annuqayah
cd emall-annuqayah

# 2. Install dependency PHP & JS
composer install
npm install

# 3. Salin file environment & generate APP_KEY
cp .env.example .env
php artisan key:generate

# 4. Buat database MySQL kosong, lalu sesuaikan .env (lihat tabel di bawah)

# 5. Jalankan migrasi + seeder data contoh
php artisan migrate --seed

# 6. Buat symlink storage (untuk upload surat keterangan & foto santri)
php artisan storage:link

# 7. Build asset frontend
npm run build

# 8. Jalankan server development
php artisan serve

Untuk mode development dengan hot-reload Tailwind/Vite, jalankan npm run dev di terminal terpisah (biarkan berjalan), lalu php artisan serve di terminal lain. Atau pakai composer run dev yang sudah disiapkan di composer.json untuk menjalankan server, queue listener, dan Vite sekaligus.

Variabel Environment (.env) Penting

Key	Keterangan
`APP_URL`	URL aplikasi. Wajib HTTPS publik yang benar di produksi — dipakai Midtrans untuk redirect & dipakai untuk generate URL webhook.
`DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`, `DB_HOST`, `DB_PORT`	Koneksi MySQL.
`MIDTRANS_SERVER_KEY`, `MIDTRANS_CLIENT_KEY`, `MIDTRANS_IS_PRODUCTION`	Nilai default/fallback saja — kredensial aktif sebenarnya diatur admin lewat halaman `/admin/pengaturan/midtrans` di aplikasi (tersimpan terenkripsi di tabel `settings`), bukan lewat file ini setelah aplikasi berjalan.
`SESSION_DRIVER`, `QUEUE_CONNECTION`, `CACHE_STORE`	Default `database` — tidak perlu Redis untuk skala pondok pada umumnya.
`DB_DUMP_BINARY_PATH`	Folder yang berisi `mysqldump` dan `mysql`. Kosongkan di Linux/shared hosting agar binary dicari dari PATH server. Isi hanya bila provider memberi lokasi khusus; jangan membawa path Windows/Laragon ke produksi.
`CRON_SECRET`	Token acak untuk endpoint cron HTTP fallback. Hanya diperlukan bila panel hosting tidak bisa menjalankan perintah Artisan langsung.

Data Contoh (Seeder)

php artisan migrate --seed membuat data contoh lengkap: 3 lembaga, ~28 santri (termasuk skenario 1 keluarga dengan 3 anak untuk uji fitur switch akun wali), jenis & tagihan bulan berjalan, kebijakan penarikan aktif, kartu santri, serta akun login berikut (kata sandi semua password):

Role	Login
Admin	`admin@pesantren.test`
Bendahara	`bendahara@pesantren.test`
Pengasuh	`pengasuh@pesantren.test`
Wali (punya 3 anak tertaut)	`wali@pesantren.test`
Santri	NIS `1001000001`
Dev (halaman ini)	`dev@pesantren.test`

Seeder juga mencetak token akses perangkat kiosk contoh (KIOSK-01) ke output terminal saat dijalankan — salin dari sana jika ingin mencoba API kiosk secara manual.

Menjalankan Test

php artisan test
# atau
./vendor/bin/pest

Test memakai SQLite in-memory (dikonfigurasi di phpunit.xml), jadi tidak menyentuh database MySQL development.

Untuk perubahan API mobile, minimal jalankan tests/Feature/Api/WaliApiTest.php dan verifikasi tipe JSON, bukan hanya nilai. Perbedaan driver MySQL/PDO antar-hosting dapat mengekspos BIGINT/DECIMAL sebagai string; Laravel Resources harus mengubahnya menjadi integer/boolean sesuai kontrak.

Setup Midtrans (Sandbox → Produksi)

Daftar akun di dashboard.midtrans.com, mulai dengan environment Sandbox.
Ambil Server Key & Client Key dari menu Settings → Access Keys.
Login sebagai admin di aplikasi, buka /admin/pengaturan/midtrans, isi kedua key tsb, biarkan "Mode Produksi" nonaktif untuk uji coba.
Di dashboard Midtrans, atur Payment Notification URL ke https://<domain-aplikasi>/midtrans/webhook — ini wajib publicly reachable (tidak bisa localhost) agar Midtrans bisa mengirim notifikasi status pembayaran.
Setelah yakin, ganti ke kredensial produksi & centang "Mode Produksi" di halaman pengaturan yang sama.

Menguji webhook Midtrans saat development lokal

Notifikasi Midtrans (webhook) dikirim server-to-server dari server Midtrans ke aplikasi kita — ini tidak bisa menjangkau localhost/127.0.0.1, karena itu bukan alamat yang bisa diakses dari internet. Akibatnya, saat testing top up di komputer lokal, pembayaran bisa saja sukses di sisi Midtrans tapi saldo tidak pernah ter-update di aplikasi, karena notifikasinya tidak pernah sampai.

Dua cara mengatasi ini:

Tombol "Cek Status Sekarang" di halaman top up wali (atau POST /api/wali/topup/{id}/sync untuk mobile) — mengambil status langsung dari Midtrans tanpa perlu menunggu webhook. Paling praktis untuk development sehari-hari, tidak perlu tool tambahan.
Tunnel publik (mis. ngrok, atau fitur tunnel bawaan Laragon) — jalankan ngrok http 8000, lalu set URL ngrok yang didapat (mis. https://xxxx.ngrok-free.app/midtrans/webhook) sebagai Payment Notification URL di dashboard Midtrans. Cara ini menguji alur webhook yang sesungguhnya, cocok dipakai sebelum go-live.

Troubleshooting backup hosting: path mysqldump masih menunjuk ke Laragon

Konfigurasi produksi dapat diatur langsung melalui Backup & Restore → Konfigurasi Hosting, tanpa mengubah .env. Gunakan mode Otomatis agar sistem mencari mysqldump/mysql dari PATH Linux dan lokasi umum seperti /usr/bin, lalu beralih ke PHP/PDO jika binary tidak tersedia. Mode MySQL CLI mewajibkan folder binary valid, sedangkan mode PHP/PDO tidak membutuhkan binary. Pengaturan disimpan terenkripsi di tabel settings. DB_DUMP_BINARY_PATH tetap tersedia sebagai fallback instalasi awal sebelum pengaturan disimpan.

Troubleshooting: "CURL Error: SSL certificate ... unable to get local issuer certificate"

Error ini muncul saat top up wali dipicu, khususnya di instalasi PHP Windows (XAMPP/Laragon) yang curl.cainfo-nya belum diset di php.ini — cURL tidak tahu di mana file sertifikat CA-nya, jadi semua request HTTPS keluar gagal verifikasi SSL, bukan cuma ke Midtrans. Sudah ditangani di kode: TopupWaliService otomatis mengarahkan cURL ke vendor/midtrans/midtrans-php/data/cacert.pem (dibawa oleh package Midtrans sendiri), jadi seharusnya sudah beres begitu composer install dijalankan. Kalau masih muncul juga (mis. di balik proxy korporat yang melakukan SSL inspection), set curl.cainfo di php.ini menunjuk ke bundel CA yang sesuai lingkungan tsb, lalu restart PHP.

Menjalankan Style & Lint

./vendor/bin/pint

Menormalkan gaya kode PHP sesuai preset Laravel. Aman dijalankan kapan saja, hanya mengubah format, bukan logika.