# PANDUAN INSTALASI SIPIUTANG DI cPANEL / SHARED HOSTING

Versi 1.0.0 — panduan langkah demi langkah untuk memasang SIPIUTANG pada hosting cPanel
tanpa memerlukan akses SSH, Node.js, atau Composer.

---

## Daftar Isi

1. [Kebutuhan Minimum](#1-kebutuhan-minimum)
2. [Persiapan Sebelum Memasang](#2-persiapan-sebelum-memasang)
3. [Langkah 1 — Mengunggah Berkas](#3-langkah-1--mengunggah-berkas)
4. [Langkah 2 — Menentukan Document Root](#4-langkah-2--menentukan-document-root)
5. [Langkah 3 — Membuat Basis Data](#5-langkah-3--membuat-basis-data)
6. [Langkah 4 — Mengatur Izin Folder](#6-langkah-4--mengatur-izin-folder)
7. [Langkah 5 — Menjalankan Wizard Instalasi](#7-langkah-5--menjalankan-wizard-instalasi)
8. [Langkah 6 — Pengamanan Setelah Instalasi](#8-langkah-6--pengamanan-setelah-instalasi)
9. [Langkah 7 — Mengaktifkan HTTPS](#9-langkah-7--mengaktifkan-https)
10. [Langkah 8 — Menjadwalkan Pencadangan Otomatis](#10-langkah-8--menjadwalkan-pencadangan-otomatis)
11. [Instalasi Manual Tanpa Wizard](#11-instalasi-manual-tanpa-wizard)
12. [Instalasi di Localhost (XAMPP/Laragon)](#12-instalasi-di-localhost-xampplaragon)
13. [Pemecahan Masalah](#13-pemecahan-masalah)
14. [Pemutakhiran Versi](#14-pemutakhiran-versi)
15. [Ceklis Instalasi](#15-ceklis-instalasi)

---

## 1. Kebutuhan Minimum

| Komponen | Minimum | Disarankan |
|---|---|---|
| PHP | 8.1 | 8.2 atau 8.3 |
| MySQL | 5.7 | 8.0 |
| MariaDB | 10.4 | 10.6 atau lebih baru |
| Ruang disk | 150 MB | 500 MB (termasuk cadangan) |
| Memori PHP | 128 MB | 256 MB |
| Batas unggah | 16 MB | 64 MB |
| Batas eksekusi | 120 detik | 300 detik |

**Ekstensi PHP wajib:** `pdo`, `pdo_mysql`, `mbstring`, `json`, `zip`, `xmlreader`,
`openssl`, `fileinfo`.
**Ekstensi opsional:** `gd` (thumbnail lampiran), `intl` (pemformatan locale).

**Tidak dibutuhkan:** Node.js, npm, Composer, Redis, Docker, akses SSH, ataupun
akses ke jaringan internet dari sisi server. Seluruh aset (Bootstrap, Chart.js, ikon)
sudah disertakan di dalam paket.

---

## 2. Persiapan Sebelum Memasang

Siapkan hal-hal berikut:

1. Berkas paket `sipiutang-v1.0.0.zip`.
2. Akses ke cPanel (URL, nama pengguna, kata sandi).
3. Nama domain atau subdomain yang akan dipakai.
4. Waktu sekitar 20–30 menit.

**Menaikkan versi PHP terlebih dahulu:**
cPanel → **MultiPHP Manager** → centang domain → pilih **PHP 8.2** → **Apply**.

**Memeriksa ekstensi PHP:**
cPanel → **Select PHP Version** → tab **Extensions** → pastikan ekstensi wajib tercentang →
klik **Save**.

---

## 3. Langkah 1 — Mengunggah Berkas

1. Masuk ke cPanel → **File Manager**.
2. Buka folder `public_html` (atau folder subdomain Anda).
3. Klik **Upload**, pilih `sipiutang-v1.0.0.zip`, tunggu hingga selesai.
4. Kembali ke File Manager, klik kanan berkas ZIP → **Extract**.
5. Setelah selesai, hapus berkas ZIP untuk menghemat ruang.

**Struktur hasil ekstraksi:**

```
sipiutang/
├── app/            Kode aplikasi (Controller, Model, Service, View)
├── config/         Berkas konfigurasi
├── database/       Skema SQL, seeder, skrip import & pencadangan
├── docs/           Dokumentasi
├── install/        Wizard instalasi — HAPUS setelah selesai
├── public/         Document root (index.php, aset, .htaccess)
├── storage/        Unggahan, ekspor, log, cadangan — harus dapat ditulis
├── tests/          Berkas pengujian
├── composer.json
└── README.md
```

---

## 4. Langkah 2 — Menentukan Document Root

Hanya folder `public/` yang boleh diakses dari internet. Folder lain harus berada di luar
jangkauan peramban. Pilih **salah satu** cara berikut.

### Cara A — Mengubah Document Root (paling aman, disarankan)

Untuk **subdomain**:
cPanel → **Domains** → **Create A New Domain** → isi nama subdomain →
hilangkan centang *"Share document root"* → isi **Document Root**:
`/home/namaakun/sipiutang/public` → **Submit**.

Untuk **domain utama**:
cPanel → **Domains** → klik ikon pensil pada domain → ubah Document Root menjadi
`/home/namaakun/sipiutang/public` → **Save**.

### Cara B — Menaruh isi `public/` di `public_html`

Bila penyedia hosting tidak mengizinkan perubahan document root:

1. Pindahkan seluruh isi folder `public/` ke `public_html/`.
2. Pindahkan folder `app`, `config`, `database`, `storage`, `docs`, `install`
   ke **satu tingkat di atas** `public_html`, misalnya `/home/namaakun/sipiutang-core/`.
3. Buka `public_html/index.php` dan sesuaikan barisnya:

   ```php
   require dirname(__DIR__) . '/sipiutang-core/app/bootstrap.php';
   ```

### Cara C — Subfolder (paling sederhana, keamanan lebih rendah)

Biarkan struktur apa adanya di `public_html/sipiutang/`, lalu akses melalui
`https://domainanda.com/sipiutang/public/`. Berkas `.htaccess` yang disertakan sudah
memblokir akses langsung ke folder `app`, `config`, `database`, dan `storage`,
namun Cara A tetap lebih dianjurkan.

---

## 5. Langkah 3 — Membuat Basis Data

1. cPanel → **MySQL® Databases**.
2. **Create New Database** — isi nama, misalnya `sipiutang`.
   cPanel otomatis menambahkan awalan akun, sehingga menjadi `namaakun_sipiutang`.
   **Catat nama lengkapnya.**
3. **MySQL Users → Add New User** — isi nama pengguna dan kata sandi yang kuat
   (gunakan *Password Generator*). **Catat keduanya.**
4. **Add User To Database** — pilih pengguna dan basis data yang baru dibuat →
   **Add** → centang **ALL PRIVILEGES** → **Make Changes**.

> **Catatan:** wizard instalasi dapat membuat basis data secara otomatis, tetapi pada
> sebagian besar hosting cPanel pengguna basis data tidak memiliki hak `CREATE DATABASE`.
> Karena itu membuatnya manual seperti di atas lebih dapat diandalkan.

---

## 6. Langkah 4 — Mengatur Izin Folder

Di File Manager, klik kanan setiap folder berikut → **Change Permissions** → isi `755`:

- `storage`
- `storage/uploads`
- `storage/exports`
- `storage/logs`
- `storage/backups`
- `storage/tmp`
- `config`

Bila setelah instalasi muncul pesan gagal menulis, naikkan menjadi `775`.
Jangan menggunakan `777`.

Setelah instalasi selesai, ubah izin berkas `config/config.php` menjadi `644`.

---

## 7. Langkah 5 — Menjalankan Wizard Instalasi

Buka di peramban:

```
https://domainanda.com/install/
```

atau, bila memakai Cara C: `https://domainanda.com/sipiutang/install/`

### Langkah 1 — Pemeriksaan Kebutuhan Sistem

Wizard memeriksa versi PHP, ekstensi, batas memori, batas unggah, batas waktu eksekusi,
dan izin tulis folder. Baris bertanda **Wajib** harus berstatus OK.
Bila ada yang gagal, ikuti saran pada kolom keterangan lalu klik **Periksa Ulang**.

### Langkah 2 — Konfigurasi Basis Data

Isi host (`localhost`), port (`3306`), nama basis data, nama pengguna, dan kata sandi
yang Anda catat pada Langkah 3. Klik **Uji Koneksi & Lanjut**.

### Langkah 3 — Pemasangan Skema & Data

Pilih salah satu:

| Pilihan | Isi | Cocok untuk |
|---|---|---|
| Struktur + master + data contoh | 49 tabel, seluruh data master, 3.072 invoice, 1.210 customer, 2.281 pembayaran | Pelatihan, uji coba, penelusuran fitur |
| Struktur + master saja | 49 tabel dan data master, tanpa transaksi | Penggunaan produksi |

Klik **Pasang Sekarang** dan **jangan menutup halaman** hingga selesai
(biasanya 30–90 detik).

### Langkah 4 — Akun Administrator

Isi nama lengkap, nama pengguna, email, nama perusahaan, dan kata sandi
(minimal 8 karakter, memuat huruf besar, huruf kecil, dan angka).

Biarkan **Nonaktifkan akun demo bawaan** tercentang untuk pemasangan produksi.

Kosongkan **URL Dasar Aplikasi** bila memakai Cara A atau B. Isi `/sipiutang/public`
bila memakai Cara C.

### Langkah 5 — Selesai

Wizard menampilkan ringkasan dan daftar langkah pengamanan. Ikuti seluruhnya.

---

## 8. Langkah 6 — Pengamanan Setelah Instalasi

**Wajib dilakukan:**

1. **Hapus folder `install/`** melalui File Manager. Selama folder ini ada,
   siapa pun dapat memasang ulang sistem Anda dan menghapus seluruh data.
2. **Ubah izin `config/config.php` menjadi `644`** (atau `640` bila hosting mengizinkan).
3. **Pastikan folder `app`, `config`, `database`, `storage` tidak dapat diakses lewat peramban.**
   Ujilah dengan membuka `https://domainanda.com/config/config.php` — hasilnya harus
   *403 Forbidden* atau *404 Not Found*, bukan menampilkan isi berkas.
4. **Nonaktifkan akun demo** bila belum: masuk sebagai administrator →
   menu **Pengguna** → nonaktifkan `superadmin`, `finance`, `collection`, `sales`,
   `manajemen`, `auditor`.
5. **Periksa berkas `.htaccess`** ada di `public/`. Berkas ini mengatur pengalihan URL,
   header keamanan, kompresi, dan pemblokiran berkas sensitif.

**Disarankan:**

- Aktifkan autentikasi dua faktor pada akun cPanel Anda.
- Batasi akses ke `/install` dan `/pengaturan` melalui IP bila hosting mendukungnya.
- Atur ulang kata sandi basis data secara berkala.

---

## 9. Langkah 7 — Mengaktifkan HTTPS

1. cPanel → **SSL/TLS Status** → centang domain → **Run AutoSSL**.
   Sertifikat Let's Encrypt gratis akan dipasang dalam beberapa menit.
2. Setelah aktif, paksa seluruh lalu lintas ke HTTPS dengan menambahkan baris berikut
   di bagian **paling atas** berkas `public/.htaccess`:

   ```apache
   RewriteEngine On
   RewriteCond %{HTTPS} !=on
   RewriteRule ^(.*)$ https://%{HTTP_HOST}%{REQUEST_URI} [L,R=301]
   ```

3. Muat ulang aplikasi dan pastikan ikon gembok muncul di peramban.

> Tanpa HTTPS, kata sandi dan data keuangan dikirim tanpa enkripsi. Jangan menggunakan
> sistem ini di jaringan publik tanpa HTTPS.

---

## 10. Langkah 8 — Menjadwalkan Pencadangan Otomatis

1. cPanel → **Cron Jobs**.
2. Pada **Common Settings**, pilih **Once Per Day (0 0 * * *)**, lalu ubah jamnya menjadi 2.
3. Isi **Command**:

   ```
   /usr/local/bin/php /home/namaakun/sipiutang/database/backup.php --quiet
   ```

   Sesuaikan `namaakun` dan lokasi folder. Jalur PHP dapat dilihat di
   cPanel → **Select PHP Version** (biasanya `/usr/local/bin/php` atau `/usr/bin/php`).

4. Klik **Add New Cron Job**.
5. Uji secara manual dengan menjalankan perintah yang sama dari **Terminal** cPanel
   (bila tersedia), atau jalankan pencadangan manual dari menu **Pencadangan Data**.

Rincian lengkap termasuk cara memulihkan ada pada `PANDUAN_BACKUP_RESTORE.md`.

---

## 11. Instalasi Manual Tanpa Wizard

Bila wizard tidak dapat dijalankan (misalnya sesi PHP dinonaktifkan):

1. **Impor SQL** melalui cPanel → **phpMyAdmin** → pilih basis data → tab **Import**,
   lalu unggah berurutan:

   ```
   database/01_schema.sql        (struktur 49 tabel)
   database/02_seed_master.sql   (data master, peran, hak akses, pengaturan)
   database/03_seed_data.sql     (opsional: data contoh dari workbook Excel)
   ```

   Bila `03_seed_data.sql` (2,5 MB) melebihi batas unggah phpMyAdmin, naikkan
   `upload_max_filesize` dan `post_max_size`, atau pecah berkas tersebut.

2. **Buat berkas konfigurasi**: salin `config/config.sample.php` menjadi
   `config/config.php`, lalu isi bagian `db` dengan kredensial Anda dan ganti
   nilai `key` dengan 32 karakter acak.

3. **Buat penanda instalasi**: buat berkas kosong bernama `storage/.installed`.

4. **Buat akun administrator**. Jalankan di phpMyAdmin → tab **SQL**
   (ganti nilai hash dengan hasil `password_hash()` PHP 8 memakai bcrypt cost 12):

   ```sql
   UPDATE users
      SET username = 'admin_anda',
          name     = 'Nama Anda',
          email    = 'email@anda.com',
          password_hash = '$2y$12$......',
          must_change_password = 0,
          is_active = 1
    WHERE id = 1;
   ```

   Untuk menghasilkan hash tanpa akses PHP CLI, buat berkas sementara `hash.php`
   di `public/` berisi:

   ```php
   <?php echo password_hash('KataSandiAnda', PASSWORD_BCRYPT, ['cost' => 12]);
   ```

   buka di peramban, salin hasilnya, lalu **hapus berkas tersebut**.

5. **Hapus folder `install/`**.

---

## 12. Instalasi di Localhost (XAMPP/Laragon)

Untuk keperluan pengembangan atau pelatihan di komputer lokal:

1. Ekstrak paket ke `C:\xampp\htdocs\sipiutang` (atau `laragon\www\sipiutang`).
2. Jalankan Apache dan MySQL dari panel kontrol.
3. Buka `http://localhost/phpmyadmin`, buat basis data `sipiutang`
   dengan *collation* `utf8mb4_unicode_ci`.
4. Buka `http://localhost/sipiutang/install/`.
5. Pada langkah basis data isi: host `localhost`, pengguna `root`, kata sandi kosong
   (bawaan XAMPP).
6. Pada langkah akun, isi **URL Dasar Aplikasi** dengan `/sipiutang/public`.

Alternatif memakai server bawaan PHP (tanpa Apache):

```bash
cd sipiutang
php -S localhost:8000 -t public
```

lalu buka `http://localhost:8000`.

---

## 13. Pemecahan Masalah

### Halaman putih / *HTTP 500*

Aktifkan sementara mode pengembangan pada `config/config.php`:

```php
'env'   => 'development',
'debug' => true,
```

Muat ulang halaman untuk melihat pesan kesalahannya, lalu **kembalikan ke `production`**
setelah selesai. Log tersimpan di `storage/logs/app-YYYY-MM-DD.log`.

### *404 Not Found* pada semua halaman kecuali beranda

Modul `mod_rewrite` belum aktif, atau `.htaccess` diabaikan. Hubungi penyedia hosting
dan minta `AllowOverride All` diaktifkan untuk direktori Anda.

### "Konfigurasi basis data belum tersedia"

Berkas `config/config.php` belum ada atau tidak terbaca. Periksa keberadaan dan izinnya (`644`).

### "SQLSTATE[HY000] [1045] Access denied"

Nama pengguna atau kata sandi basis data salah, atau pengguna belum diberi
*ALL PRIVILEGES* pada basis data tersebut.

### "SQLSTATE[HY000] [2002] Connection refused"

Host basis data salah. Pada cPanel hampir selalu `localhost`, bukan `127.0.0.1`.

### Aset (CSS/JS) tidak termuat, tampilan berantakan

Nilai `base_url` tidak sesuai. Buka `config/config.php` dan sesuaikan, misalnya
`'base_url' => '/sipiutang/public'`. Kosongkan bila document root sudah menunjuk ke `public/`.

### Import Excel gagal atau berhenti di tengah

Naikkan batas pada `public/.htaccess`:

```apache
php_value upload_max_filesize 64M
php_value post_max_size 64M
php_value memory_limit 512M
php_value max_execution_time 600
```

Bila hosting menolak arahan `php_value`, gunakan cPanel → **MultiPHP INI Editor**.

### Ekspor PDF kosong atau rusak

Sistem memakai generator PDF internal yang tidak memerlukan pustaka tambahan.
Bila hasilnya tetap bermasalah, pasang Dompdf melalui Composer — sistem akan
mendeteksi dan memakainya secara otomatis.

### Sesi selalu berakhir / terus diminta login

Folder sesi PHP tidak dapat ditulis. Tambahkan pada `public/.htaccess`:

```apache
php_value session.save_path "/home/namaakun/tmp"
```

lalu pastikan folder tersebut ada dan berizin `755`.

### Zona waktu tidak sesuai

Pastikan `'timezone' => 'Asia/Jakarta'` pada `config/config.php`.

---

## 14. Pemutakhiran Versi

1. **Cadangkan terlebih dahulu**: jalankan pencadangan dari menu Pencadangan Data,
   lalu unduh berkasnya. Salin juga folder `config/` dan `storage/uploads/`.
2. Unggah dan ekstrak paket versi baru ke folder sementara.
3. Timpa folder `app/`, `public/`, `database/`, dan `docs/` dengan versi baru.
4. **Jangan menimpa** `config/config.php` dan folder `storage/`.
5. Bila catatan rilis menyebutkan perubahan skema, jalankan berkas migrasi yang disertakan
   melalui phpMyAdmin.
6. Masuk sebagai administrator, buka **Pengaturan → Hitung Ulang Piutang**,
   dan jalankan sekali.
7. Periksa dashboard dan beberapa laporan untuk memastikan semuanya normal.

---

## 15. Ceklis Instalasi

Cetak dan centang selama proses pemasangan.

| No | Butir | ✓ |
|---|---|---|
| 1 | PHP 8.1+ aktif untuk domain | ☐ |
| 2 | Ekstensi wajib aktif (pdo_mysql, mbstring, zip, xmlreader, openssl, fileinfo) | ☐ |
| 3 | Paket terunggah dan terekstrak | ☐ |
| 4 | Document root menunjuk ke folder `public/` | ☐ |
| 5 | Basis data dan penggunanya dibuat, ALL PRIVILEGES diberikan | ☐ |
| 6 | Folder `storage/*` dan `config` berizin 755 | ☐ |
| 7 | Wizard langkah 1 — seluruh kebutuhan wajib OK | ☐ |
| 8 | Wizard langkah 2 — koneksi basis data berhasil | ☐ |
| 9 | Wizard langkah 3 — skema dan data terpasang | ☐ |
| 10 | Wizard langkah 4 — akun administrator dibuat | ☐ |
| 11 | Berhasil masuk memakai akun administrator | ☐ |
| 12 | Dashboard menampilkan angka dengan benar | ☐ |
| 13 | **Folder `install/` sudah dihapus** | ☐ |
| 14 | `config/config.php` berizin 644 | ☐ |
| 15 | `https://domain/config/config.php` mengembalikan 403/404 | ☐ |
| 16 | Akun demo dinonaktifkan | ☐ |
| 17 | HTTPS aktif dan pengalihan otomatis berfungsi | ☐ |
| 18 | Cron pencadangan harian terpasang | ☐ |
| 19 | Pencadangan manual berhasil dan berkasnya dapat diunduh | ☐ |
| 20 | Ceklis pengujian pada `CHECKLIST_PENGUJIAN.md` dijalankan | ☐ |

---

*Dokumen ini merupakan bagian dari paket SIPIUTANG v1.0.0.*