# Panduan Instalasi — Aplikasi Service Elektronik

Panduan lengkap untuk menjalankan aplikasi di laptop / komputer baru.

---

## Kebutuhan Sistem

| Komponen | Versi Minimal | Keterangan |
|----------|---------------|------------|
| **PHP** | 8.2+ | Wajib |
| **Composer** | 2.x | Untuk install dependencies |
| **MySQL / MariaDB** | 5.7+ | Opsional (bisa pakai SQLite trial) |
| **Web Browser** | Chrome / Edge / Firefox | Modern browser |

---

## 1. Install PHP 8.2+

### Windows

1. Download PHP Windows dari: https://windows.php.net/download/
   - Pilih versi **PHP 8.2** atau **PHP 8.3**
   - Pilih varian **VS16 x64 Thread Safe** (file `.zip`)

2. Ekstrak ke `C:\php`

3. Tambahkan `C:\php` ke **Environment Variable PATH**:
   - Buka **Start** → ketik `environment variables` → buka "Edit the system environment variables"
   - Klik **Environment Variables**
   - Di bagian **System variables**, pilih `Path` → klik **Edit** → **New** → ketik `C:\php`
   - OK semua dialog

4. Buka Terminal baru, test:
   ```bash
   php --version
   ```

### Aktifkan Extension PHP yang Dibutuhkan

Buka file `C:\php\php.ini` (copy dari `php.ini-development` jika belum ada), lalu cari dan **hapus tanda `;`** di depan baris berikut:

```ini
extension=pdo_mysql
extension=pdo_sqlite
extension=sqlite3
extension=mbstring
extension=openssl
extension=tokenizer
extension=xml
extension=ctype
extension=json
extension=bcmath
extension=fileinfo
extension=curl
extension=gd
```

Simpan, lalu restart terminal.

---

## 2. Install Composer

1. Download installer: https://getcomposer.org/Composer-Setup.exe
2. Jalankan installer — arahkan ke `C:\php\php.exe`
3. Test di terminal:
   ```bash
   composer --version
   ```

> **Alternatif**: Download `composer.phar` ke `C:\php\`, lalu jalankan dengan `php C:\php\composer.phar`.

---

## 3. Install MySQL (Opsional)

Jika hanya untuk **demo / trial**, lewati langkah ini dan langsung ke langkah 4 (bisa pakai mode SQLite).

### Pakai XAMPP (Termudah)

1. Download XAMPP: https://www.apachefriends.org/
2. Install, lalu jalankan **XAMPP Control Panel**
3. Start **MySQL**
4. Buka http://localhost/phpmyadmin
5. Buat database baru bernama **`svc`**

### Pakai Laragon

1. Download: https://laragon.org/
2. Install, jalankan Laragon
3. Start MySQL
4. Klik **Database** → Create database → nama `svc`

---

## 4. Setup Aplikasi

### Cara Otomatis (Disarankan)

1. Copy seluruh folder aplikasi ke laptop baru (misal: `D:\svc\`)
2. Buka Terminal di folder tersebut (klik kanan → "Open Terminal here" atau `cd D:\svc`)
3. Jalankan:
   ```bash
   setup.bat
   ```
4. Ikuti instruksi yang muncul:
   - Pilih mode database: **[1] MySQL** atau **[2] SQLite Trial**
   - Tunggu sampai setup selesai

### Cara Manual

Jika `setup.bat` gagal, jalankan satu per satu:

```bash
# 1. Install dependencies
composer install

# 2. Copy file konfigurasi
copy .env.example .env

# 3. Generate application key
php artisan key:generate

# 4. Edit file .env — sesuaikan DB_DATABASE, DB_USERNAME, DB_PASSWORD
notepad .env

# 5. Migrasi + seed database
php artisan migrate:fresh --seed

# 6. Buat symbolic link storage
php artisan storage:link
```

### Konfigurasi .env

Edit `.env` dan pastikan:

```env
APP_NAME="Service Elektronik"
APP_ENV=local
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=svc
DB_USERNAME=root
DB_PASSWORD=
```

> **Password MySQL** biasanya kosong di XAMPP default. Di Laragon juga kosong by default.

---

## 5. Menjalankan Aplikasi

```bash
php artisan serve
```

Buka browser: **http://localhost:8000**

### Akun Login Default

| Role | Email | Password |
|------|-------|----------|
| Admin | admin@service.com | admin123 |
| Manager | manager@service.com | manager123 |
| Resepsionis | resepsionis@service.com | resepsionis123 |
| Teknisi | budi@service.com | teknisi123 |
| Teknisi | andi@service.com | teknisi123 |

---

## 6. Mode Data: MySQL vs SQLite

Aplikasi mendukung dua mode penyimpanan data:

| Mode | Kapan Dipakai | Keterangan |
|------|---------------|------------|
| **MySQL** | Produksi | Data disimpan di server MySQL. Cocok untuk multi-user dan data besar. |
| **SQLite (Trial)** | Demo / Trial | Data disimpan dalam file lokal `storage/app/trial.sqlite`. Tidak perlu MySQL. |

### Mengubah Mode

1. Login sebagai admin
2. Buka menu **Pengaturan** → **Pengaturan Sistem**
3. Tab **Sumber Data** → klik tombol mode yang diinginkan
4. Sistem akan otomatis logout → login ulang

---

## 7. Backup & Pindah Data

### Backup
**Pengaturan Sistem** → tab **Backup & Restore** → **Download Backup JSON**

### Restore / Import ke Laptop Baru
1. Copy file `.json` hasil backup ke laptop baru
2. Setelah aplikasi terinstall, buka **Pengaturan Sistem** → **Backup & Restore**
3. Upload file JSON → **Import Pengaturan**

> Catatan: Yang diimport hanya pengaturan umum (nama perusahaan, alamat, prefix). Data transaksi tidak ikut.

---

## Troubleshooting

### `composer: command not found`
Composer belum terinstall atau belum ada di PATH. Lihat langkah 2.

### `could not find driver (Connection: sqlite)`
Extension `pdo_sqlite` belum aktif. Lihat langkah 1 — aktifkan `extension=pdo_sqlite` di `php.ini`, lalu restart server.

### `SQLSTATE[HY000] [2002] No connection could be made`
MySQL belum jalan. Start MySQL di XAMPP / Laragon.

### `Access denied for user 'root'@'localhost'`
Password MySQL salah. Edit `.env` → `DB_PASSWORD`.

### `Unknown database 'svc'`
Database belum dibuat. Buka phpMyAdmin → buat database `svc`.

### Halaman putih / error 500
```bash
php artisan config:clear
php artisan cache:clear
php artisan view:clear
```

### Port 8000 sudah dipakai
```bash
php artisan serve --port=8080
```

---

## Struktur Direktori Penting

```
svc/
├── .env                      ← Konfigurasi aplikasi (edit sesuai server)
├── setup.bat                 ← Script auto-setup Windows
├── storage/
│   └── app/
│       ├── settings.json     ← Pengaturan aplikasi (nama, alamat, prefix)
│       └── trial.sqlite      ← Database mode trial (hanya jika SQLite aktif)
├── database/
│   └── migrations/           ← Skema database
└── resources/views/          ← Tampilan/UI
```

---

## 🐳 Menjalankan dengan Docker (Alternatif)

Jika tidak ingin install PHP/MySQL manual, bisa pakai Docker.

### Prasyarat
- **Docker Desktop** (Windows/Mac) atau **Docker Engine + Docker Compose** (Linux)
- Download: https://www.docker.com/products/docker-desktop/

### Quick Start (Satu Perintah)

```powershell
docker compose up -d --build
```

Itu saja. Container akan otomatis:

1. ✅ Copy `.env.docker` → `.env` (kalau `.env` belum ada)
2. ✅ Generate `APP_KEY`
3. ✅ Composer install (kalau `vendor/` kosong / `composer.lock` baru)
4. ✅ Tunggu MySQL siap
5. ✅ Buat database `svc` (sesuai `.env`)
6. ✅ Buat user database (kalau bukan `root`)
7. ✅ `php artisan migrate` (otomatis `migrate:fresh --seed` kalau DB kosong)
8. ✅ Storage symlink
9. ✅ Clear cache (config, view, route, cache)
10. ✅ Set permission `www-data:775` untuk `storage/` & `bootstrap/cache/`
11. ✅ Start Apache

**Tunggu ~60 detik** untuk first boot (build image + MySQL init + seed). Lihat progres:

```powershell
docker compose logs -f app
```

Akan muncul output seperti ini:

```
[entrypoint] [1/10] Menyiapkan storage directories...
  ✓ Storage siap (owner: www-data, mode: 775)
[entrypoint] [2/10] Menyiapkan file .env...
  ✓ .env dibuat dari .env.docker
...
[entrypoint] [10/10] Final permission check...
  ✓ Permission final OK

═══════════════════════════════════════════════════════════════
  ✓ Setup selesai! Apache akan start...
  → URL:   http://localhost:8000
  → DB:    svc @ db (port host: 3307)
  → Login: admin@service.com / admin123
═══════════════════════════════════════════════════════════════
```

Tekan **Ctrl+C** untuk keluar dari log setelah lihat "Setup selesai".

### Kustomisasi (Opsional)

Kalau mau ubah port / database / dll — copy `.env.docker` ke `.env` SEBELUM `docker compose up`, lalu edit:

```powershell
copy .env.docker .env
# edit .env sesuai kebutuhan, contoh:
#   APP_PORT=8001
#   DB_DATABASE=mydb
#   DB_PASSWORD=rahasia
docker compose up -d --build
```

### Mengapa `vendor/` dan `node_modules/` Kosong di Host?

**Itu normal!** Container pakai **anonymous volume** untuk shield `vendor/` dan `node_modules/` — keduanya hidup di dalam image (~150MB + ~200MB) supaya:
- Build cepat (composer/npm install hanya jalan saat `docker compose build`)
- Vendor di host yang kosong tidak meng-overwrite vendor di container

**Aplikasi tetap jalan sempurna** meski folder host tampak kosong di VSCode.

#### Kalau Mau IDE Autocomplete Bekerja

Sync sekali dari container ke host:

```powershell
# Windows
docker\sync-host.bat

# Linux/Mac
bash docker/sync-host.sh
```

Setelah sync, restart VSCode → autocomplete PHP class dari Laravel/vendor akan jalan.

> Catatan: file di host hanya untuk IDE. Container tetap pakai versinya sendiri. Kalau composer.json berubah, jalankan `docker compose build` ulang lalu re-sync.

### Reset Total (kalau ada masalah)

```powershell
docker compose down -v          # stop + hapus volume DB
Remove-Item -Force .env         # hapus .env yang mungkin korup
docker compose up -d --build    # build ulang dari nol
```

### Akses Aplikasi

| Service | URL | Keterangan |
|---------|-----|------------|
| Aplikasi | http://localhost:8000 | App utama |
| phpMyAdmin | http://localhost:8080 | Kelola MySQL (user: `root`, pass: `root`) |
| MySQL (dari host) | `localhost:3307` | Koneksi DB dari luar container |

Login default:
- `admin@service.com` / `admin123`

### Perintah Docker Berguna

```bash
# Lihat status container
docker compose ps

# Lihat log aplikasi
docker compose logs -f app

# Masuk ke shell container
docker compose exec app bash

# Jalankan artisan command
docker compose exec app php artisan migrate
docker compose exec app php artisan tinker

# Jalankan composer
docker compose exec app composer install

# Stop container (data tetap tersimpan)
docker compose down

# Stop + hapus volume (data MySQL ikut terhapus)
docker compose down -v

# Rebuild image setelah ubah Dockerfile
docker compose build --no-cache
docker compose up -d
```

### Konfigurasi Port (jika bentrok)

Edit file `.env`:
```env
APP_PORT=8001              # Ganti jika 8000 dipakai
PMA_PORT=8081              # Ganti jika 8080 dipakai
DB_PORT_EXTERNAL=3308      # Ganti jika 3307 dipakai
```

Lalu restart:
```bash
docker compose down
docker compose up -d
```

### Troubleshooting Docker

**Container "app" keluar / restart loop**
```bash
docker compose logs app
# Cek errornya, biasanya tunggu MySQL siap atau APP_KEY belum di-generate
```

**Database kosong setelah restart**
- Data tersimpan di Docker volume `svc-db-data`
- Jangan pakai `docker compose down -v` kecuali memang ingin reset

**Tidak bisa akses phpMyAdmin**
- Login dengan: server `db`, user `root`, password `root`

**Change port MySQL internal?**
- Tidak perlu — port `3306` di container network tidak bentrok dengan host
- Port host adalah `DB_PORT_EXTERNAL` (default `3307`)

---

## Kontak & Bantuan

Jika ada kendala instalasi, hubungi developer / admin sistem.