# Panduan Instalasi GPCH Asset Care di cPanel

Panduan ini memasang **GPCH Asset Care** (Laravel 13 + Filament 5 + MySQL 8) di hosting cPanel, dengan pola yang sama seperti ArahGPCH:

- Folder aplikasi: `/home/cpuser/asset-care-gpch`, di **luar** `public_html`.
- Subdomain: `asset-gpch.dhastram.com`, dengan document root `asset-care-gpch/public`.

Tampilan **sama dengan ArahGPCH**: warna hijau GPCH `#006632`, ornamen wayang, serta font Inter dan Cormorant. Berkas tema ada di `public/css/assetcare.css` dan `public/images/`, jadi tidak perlu pengaturan tambahan.

> Ganti `cpuser` dengan nama pengguna cPanel Anda, dan `dhastram.com` dengan domain Anda.

---

## 0. Kebutuhan hosting

| Kebutuhan | Nilai |
|---|---|
| PHP | 8.3 atau 8.4 (MultiPHP) |
| Ekstensi PHP | pdo_mysql, mbstring, intl, gd, zip, fileinfo, openssl, xml, ctype, tokenizer |
| memory_limit | minimal 256M (untuk PDF label) |
| MySQL | 8.x (MariaDB 10.6+ umumnya juga jalan) |
| Fitur cPanel | Terminal (SSH), Cron Jobs, AutoSSL |
| Ruang disk | ±350 MB untuk aplikasi, ditambah lampiran foto |

Ekstensi diatur di **cPanel → Select PHP Version → Extensions**, atau di **MultiPHP INI Editor** untuk memory_limit.

---

## 1. Buat subdomain

1. Buka **cPanel → Domains → Create A New Domain**.
2. Isi Domain: `asset-gpch.dhastram.com`.
3. **Hapus centang** "Share document root", lalu isi Document Root: `asset-care-gpch/public`.
4. Klik **Submit**.

Jika hosting tidak mengizinkan document root di luar `public_html`, lihat **Lampiran A**.

## 2. Atur versi PHP

Buka **cPanel → MultiPHP Manager**, centang `asset-gpch.dhastram.com`, lalu pilih **PHP 8.3** (atau 8.4) dan klik **Apply**.

## 3. Buat basis data

Buka **cPanel → Manage My Databases**, atau gunakan **Database Wizard**:

1. Buat database `assetcare`. Nama lengkapnya menjadi `cpuser_assetcare`.
2. Buat user `asset` dengan sandi kuat. Nama lengkapnya menjadi `cpuser_asset`. **Catat sandinya.**
3. Tambahkan user ke database dengan **ALL PRIVILEGES**.

## 4. Unggah aplikasi

1. Buka **cPanel → File Manager** dan masuk ke folder home (`/home/cpuser`), **bukan** ke `public_html`.
2. **Upload** `asset-care-gpch-cpanel.zip`.
3. Klik kanan zip tersebut, pilih **Extract**, dan ekstrak ke `/home/cpuser`.
4. Pastikan hasilnya berupa folder `/home/cpuser/asset-care-gpch`, yang berisi `app`, `public`, `vendor`, `deploy`, dan seterusnya.
5. Hapus file zip setelah selesai diekstrak.

## 5. Siapkan file `.env`

Buka **cPanel → Terminal**, lalu jalankan:

```bash
cd ~/asset-care-gpch
cp deploy/.env.cpanel.example .env
nano .env
```

Ubah minimal nilai-nilai berikut:

| Kunci | Isi |
|---|---|
| `APP_URL` | `https://asset-gpch.dhastram.com` |
| `ASSETCARE_QR_BASE_URL` | Sama dengan APP_URL. **Tercetak permanen di label**, lihat bagian 9. |
| `DB_DATABASE` | `cpuser_assetcare` |
| `DB_USERNAME` | `cpuser_asset` |
| `DB_PASSWORD` | Sandi dari langkah 3 |
| `MAIL_HOST` / `MAIL_USERNAME` / `MAIL_PASSWORD` | Akun email cPanel untuk notifikasi, misalnya `noreply@dhastram.com` di port 465 |
| `ASSETCARE_ADMIN_PASSWORD` | Opsional. Jika kosong, sandi Super Admin dibuat acak. |
| `ASSETCARE_MFA_REQUIRED` | `true` (disarankan). Admin dan approver wajib memasang 2FA. |

Simpan dengan **Ctrl+O**, tekan **Enter**, lalu keluar dengan **Ctrl+X**. `APP_KEY` biarkan kosong karena akan diisi otomatis oleh skrip.

## 6. Instal aplikasi

Pilih **salah satu** cara berikut.

### Cara A (disarankan): skrip instalasi lewat Terminal

```bash
cd ~/asset-care-gpch
bash deploy/deploy-cpanel.sh install     # basis data bersih: referensi + Super Admin
# atau
bash deploy/deploy-cpanel.sh seed        # sama, ditambah data contoh untuk uji coba/pelatihan
```

Skrip ini melakukan langkah-langkah berikut:

1. Memeriksa PHP dan ekstensi.
2. Mengatur hak akses folder.
3. Membuat APP_KEY.
4. Menjalankan migrasi dan seed.
5. Menjalankan `storage:link` dan mempublikasikan aset Filament.
6. Menyimpan cache konfigurasi.
7. Menjalankan pemeriksaan `assetcare:doctor`.

Di akhir proses akan muncul baris seperti ini:

```
Super Admin: admin@assetcare.local  /  AC-xxxxxxxxxxxxxx  (CATAT sekarang; wajib diganti saat login pertama)
```

**Catat sandi ini.** Sandi hanya ditampilkan sekali. Skrip juga menolak berjalan dua kali pada basis data yang sudah berisi data, supaya data tidak tertimpa.

### Cara B: impor SQL lewat phpMyAdmin (bila Terminal tidak tersedia)

1. Buka **phpMyAdmin**, pilih `cpuser_assetcare`, buka **Import**, lalu impor `database/sql/asset-care-gpch.sql`.
2. Akun awal adalah `admin@assetcare.local` dengan sandi `AssetCare@GPCH2026`. Sandi ini wajib diganti saat login pertama.
3. Langkah berikutnya tetap memerlukan Terminal sekali (atau minta bantuan penyedia hosting):
   ```bash
   cd ~/asset-care-gpch && php artisan key:generate --force && bash deploy/deploy-cpanel.sh update
   ```

## 7. Aktifkan HTTPS

1. Buka **cPanel → SSL/TLS Status**, centang subdomain, lalu klik **Run AutoSSL**.
2. Buka **cPanel → Domains**, lalu aktifkan **Force HTTPS Redirect** untuk `asset-gpch.dhastram.com`.

HTTPS **wajib** karena dua alasan:

- Kamera untuk scan QR hanya berfungsi di HTTPS.
- Cookie sesi diatur sebagai *secure*.

## 8. Pasang Cron Jobs

Buka **cPanel → Cron Jobs** dan tambahkan dua baris berikut. Sesuaikan path PHP jika versinya berbeda. Path yang benar ditampilkan di akhir skrip instalasi.

| Jadwal | Perintah | Fungsi |
|---|---|---|
| Setiap menit (`* * * * *`) | `/opt/cpanel/ea-php83/root/usr/bin/php /home/cpuser/asset-care-gpch/artisan schedule:run >> /dev/null 2>&1` | Cek SLA, eskalasi, jadwal PM, dan notifikasi |
| Harian 02:00 (`0 2 * * *`) | `/bin/bash /home/cpuser/asset-care-gpch/deploy/backup-db.sh >> /home/cpuser/backups/asset-care-backup.log 2>&1` | Backup database harian dan arsip lampiran mingguan, disimpan 30 hari di `~/backups/asset-care-gpch` |

## 9. Tentukan domain QR sebelum mencetak label

Setiap label QR berisi alamat `ASSETCARE_QR_BASE_URL/q/...`. **Setelah label dicetak dan ditempel, alamat ini tidak bisa diubah.** Karena itu:

- Tentukan domain final terlebih dahulu, misalnya `asset-gpch.dhastram.com` atau domain resmi hotel.
- Jika domain diganti, ubah `ASSETCARE_QR_BASE_URL` di `.env` lalu jalankan `php artisan optimize`, **sebelum** mencetak massal.
- Cetak 1 lembar uji, lalu scan dengan HP untuk memastikan alamatnya membuka halaman aset yang benar.

## 10. Verifikasi

| Cek | Hasil yang diharapkan |
|---|---|
| Buka `https://asset-gpch.dhastram.com` | Halaman login bertema ArahGPCH (hijau, wayang) |
| Buka `https://asset-gpch.dhastram.com/.env` | **404**. Jika file .env terlihat, document root salah. Ulangi langkah 1. |
| `php artisan assetcare:doctor` di Terminal | Semua baris berstatus **OK** |
| Login sebagai Super Admin | Diminta mengganti sandi, lalu memasang 2FA (Google Authenticator) |
| Aset → pilih aset → **Cetak label PDF** | PDF A4 3×9 berisi QR, kode, nama, dan ruang |
| Menu **Scan QR** di HP | Kamera aktif dan label terbaca |

---

## Memperbarui ke rilis baru

1. Backup terlebih dahulu: `bash deploy/backup-db.sh`.
2. Unggah zip rilis baru, lalu ekstrak **menimpa** `~/asset-care-gpch`. File `.env` dan `storage/` tidak ikut tertimpa karena tidak ada di dalam paket.
3. Jalankan:
   ```bash
   cd ~/asset-care-gpch && bash deploy/deploy-cpanel.sh update
   ```
   Skrip ini akan memasang mode maintenance, menjalankan migrasi, memperbarui data referensi, membangun ulang cache, lalu menonaktifkan maintenance. Akun dan data tidak berubah.

## Memulihkan dari backup

```bash
gunzip -c ~/backups/asset-care-gpch/cpuser_assetcare_YYYY-MM-DD_HHMM.sql.gz | mysql -u cpuser_asset -p cpuser_assetcare
tar -xzf ~/backups/asset-care-gpch/lampiran_YYYY-MM-DD.tar.gz -C ~/asset-care-gpch/storage/app
cd ~/asset-care-gpch && php artisan optimize:clear && php artisan optimize
```

> Simpan juga salinan file `.env` di tempat aman. **APP_KEY** dibutuhkan untuk membaca token label QR yang terenkripsi. Jika APP_KEY hilang, semua label harus dicetak ulang.

## Masalah umum

| Gejala | Penyebab dan solusi |
|---|---|
| Error 500 atau halaman putih | Lihat `storage/logs/laravel.log`. Biasanya disebabkan sandi DB salah atau `.env` belum lengkap. Setelah mengubah .env, jalankan `php artisan optimize`. |
| "Ekstensi ... tidak ada" saat menjalankan skrip | Aktifkan ekstensi di **Select PHP Version → Extensions** |
| Tampilan berantakan tanpa CSS | `APP_URL` tidak sama dengan alamat yang dibuka (http atau https). Perbaiki, lalu jalankan `php artisan optimize`. Jalankan juga `php artisan filament:assets`. |
| Foto atau lampiran tidak tampil | Jalankan `php artisan storage:link` |
| Login berulang kali kembali ke halaman login | Situs dibuka lewat http, padahal `SESSION_SECURE_COOKIE=true`. Aktifkan Force HTTPS. |
| Kamera scan tidak muncul | Situs belum HTTPS, atau izin kamera di browser ditolak |
| SLA atau notifikasi tidak berjalan | Cron `schedule:run` belum terpasang atau path PHP salah |
| PDF label gagal untuk banyak aset | Naikkan `memory_limit` ke 512M, atau cetak per ruang/kategori |
| Lupa sandi Super Admin | `php artisan assetcare:create-admin` untuk membuat admin baru |

## Lampiran A: jika document root harus di dalam `public_html`

**Opsi 1: symlink** (jika diizinkan hosting)

```bash
rm -rf ~/public_html/asset-gpch        # hanya jika folder ini kosong/bawaan subdomain
ln -s ~/asset-care-gpch/public ~/public_html/asset-gpch
```

Setelah itu, atur document root subdomain ke `public_html/asset-gpch`.

**Opsi 2: salin isi folder `public`**

1. Salin seluruh isi `~/asset-care-gpch/public/` ke `~/public_html/asset-gpch/`.
2. Edit `~/public_html/asset-gpch/index.php` dan ubah path-nya:
   ```php
   require __DIR__.'/../../asset-care-gpch/vendor/autoload.php';
   $app = require_once __DIR__.'/../../asset-care-gpch/bootstrap/app.php';
   ```
   Jika baris `maintenance.php` ada, ubah dengan pola yang sama ke `/../../asset-care-gpch/storage/framework/maintenance.php`.
3. Buat ulang tautan storage:
   ```bash
   ln -s ~/asset-care-gpch/storage/app/public ~/public_html/asset-gpch/storage
   ```
4. Setiap kali ada pembaruan, salin ulang `public/css`, `public/js`, dan `public/images`, lalu jalankan `php artisan filament:assets`.

## Catatan keamanan

- `APP_DEBUG=false` dan `APP_ENV=production`. Jangan ubah di server.
- `.env` sudah diatur dengan `chmod 600` oleh skrip. Jangan simpan file ini di `public_html`.
- `robots.txt` menolak semua mesin pencari.
- Admin dan approver wajib memakai 2FA (`ASSETCARE_MFA_REQUIRED=true`).
- Ganti sandi Super Admin awal. Buat akun per orang, dan jangan memakai akun bersama.
- Pantau `~/backups/asset-care-backup.log` secara berkala, dan unduh backup ke luar server minimal sebulan sekali.

## Ringkasan nilai

| Item | Nilai |
|---|---|
| Folder aplikasi | `/home/cpuser/asset-care-gpch` |
| Document root | `asset-care-gpch/public` |
| URL | `https://asset-gpch.dhastram.com` |
| Database / user | `cpuser_assetcare` / `cpuser_asset` |
| Super Admin | `admin@assetcare.local`. Sandi ditampilkan saat instalasi (Cara A) atau `AssetCare@GPCH2026` (Cara B). |
| Cron | `schedule:run` setiap menit dan `backup-db.sh` setiap hari 02:00 |
| Backup | `~/backups/asset-care-gpch` (30 hari) |