# Local Installation and Deployment Guide (Windows 11 + XAMPP)
## Kampong Speu Provincial Demographic Management System (KSP-DMS)

**Document Code:** KSP-DMS-DOC-INST-01  
**Target Environment:** Windows 11 64-bit / XAMPP (Apache 2.4, PHP 8.2, MariaDB 10.4)  
**Version:** 1.0  

---

## 1. Prerequisites Checklist

Before installing KSP-DMS, verify that the following components are installed:
- [x] Windows 11 (64-bit)
- [x] XAMPP installed at `C:\xampp`
- [x] PHP 8.2.12 verified at `C:\xampp\php\php.exe`
- [x] MariaDB 10.4 verified at `C:\xampp\mysql\bin\mysql.exe`
- [x] Node.js (`v26.1.0` or >= 18.x) and npm (`11.13.0` or >= 9.x)
- [x] Git for Windows installed

---

## 2. Step-by-Step Installation Instructions

### Step 1: Start XAMPP Services
Open the **XAMPP Control Panel** as Administrator and start:
- **Apache** (Web Server)
- **MySQL** (Database Daemon)

Alternatively, start MySQL via command line:
```powershell
& "C:\xampp\mysql\bin\mysqld.exe" --defaults-file="C:\xampp\mysql\bin\my.ini" --standalone
```

### Step 2: Create the Local MariaDB Database
Open PowerShell and create the application database with full Unicode Khmer support:
```powershell
& "C:\xampp\mysql\bin\mysql.exe" -u root -e "CREATE DATABASE IF NOT EXISTS ksp_dms CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
```

### Step 3: Install PHP Dependencies
Using the verified PHP executable and `composer.phar`:
```powershell
cd C:\xampp\htdocs\ksp-dms
& "C:\xampp\php\php.exe" composer.phar install
```

### Step 4: Configure Environment File (`.env`)
Copy `.env.example` to `.env`:
```powershell
Copy-Item .env.example .env
```
Ensure database connection settings match your local XAMPP configuration:
```env
APP_NAME="KSP-DMS"
APP_ENV=local
APP_KEY=
APP_DEBUG=true
APP_URL=http://localhost:8000

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=ksp_dms
DB_USERNAME=root
DB_PASSWORD=
```
Generate the application key:
```powershell
& "C:\xampp\php\php.exe" artisan key:generate
```

### Step 5: Run Database Migrations and Seeders
Initialize the schema and seed synthetic Cambodian administrative divisions and demo records:
```powershell
& "C:\xampp\php\php.exe" artisan migrate:fresh --seed
```

### Step 6: Install Frontend Dependencies & Compile Assets
```powershell
npm install
npm run build
```

### Step 7: Launch the Application
Start the local development server:
```powershell
& "C:\xampp\php\php.exe" artisan serve
```
Open your web browser and navigate to:
👉 **`http://127.0.0.1:8000`**

---

## 3. Troubleshooting Common Issues

### Issue 1: `php` command not found
**Solution:** `C:\xampp\php` is not in your system `%PATH%`. Either execute using the full path `& "C:\xampp\php\php.exe"` or add `C:\xampp\php` to your user environment variables.

### Issue 2: MySQL Connection Refused (`SQLSTATE[HY000] [2002]`)
**Solution:** The MariaDB service is not running. Check XAMPP Control Panel and click "Start" next to MySQL.

### Issue 3: Khmer Characters Displaying as Question Marks (`???`)
**Solution:** Ensure the database collation is explicitly set to `utf8mb4_unicode_ci` and the browser supports Unicode Khmer fonts (such as `Khmer OS Content` or `Leelawadee UI`).
