# Election Management System — Installation Guide

## Option A: Browser-Based Installer (Recommended)

The easiest way to install — no SSH required for basic setups.

### Prerequisites
Before running the installer, you need to:
1. Create a MySQL database in cPanel
2. Have your domain pointed to the `/public` folder (or configure via .htaccess)

---

### Step 1: Upload the Files

1. Log in to **cPanel → File Manager**
2. Navigate to `public_html` (or your subdomain/addon domain folder)
3. Upload `election-system.zip` (or `election-system.tar.gz`)
4. **Extract** the archive — you should see folders like `app/`, `public/`, `resources/`, etc.

**Optional but Recommended:** Rename the extracted folder to something clean:
```
public_html/election/
```

---

### Step 2: Point Your Domain to /public

The Laravel application root is the `public/` subfolder.

**Method 1 — Set Document Root in cPanel:**
- cPanel → Domains/Subdomains → Edit domain → set Document Root to:
  ```
  public_html/election/public
  ```

**Method 2 — Use the included .htaccess (root redirect):**
- If your domain root is `public_html/election/`, the `.htaccess` file at the project root automatically redirects all traffic to `/public`

---

### Step 3: Run the Installer

Open your browser and visit:
```
https://yourdomain.com/install.php
```

The installer has **6 steps**:

| Step | What Happens |
|------|-------------|
| 1. Requirements | Checks PHP version, extensions, and file permissions |
| 2. Database | Enter your MySQL host, database name, username, and password |
| 3. App Config | Set your application name and full URL |
| 4. Admin Account | Create your super-admin email and password |
| 5. Review & Install | Confirm settings, then click Install |
| 6. Complete | Installation runs automatically — migration, seeding, key generation |

> **Tip:** If Step 5 is slow, don't close the page — Composer may be installing dependencies (takes 1–3 min).

---

### Step 4: After Installation

Once the installer completes:

1. **Delete `install.php`** immediately for security
   - File Manager → select `install.php` → Delete

2. **Log in to Admin Panel:**
   ```
   https://yourdomain.com/admin
   ```
   Use the email and password you set in Step 4 of the installer.

3. **Set up Cron Job** (for auto-closing elections):
   - cPanel → Cron Jobs → Add:
   ```
   0 * * * * /usr/local/bin/php /home/user/public_html/election/artisan schedule:run >> /dev/null 2>&1
   ```
   *(Adjust PHP path — find yours with `which php` in cPanel Terminal)*

---

## Option B: SSH / Terminal Installation

If you have SSH access:

```bash
# 1. Navigate to your project folder
cd public_html/election

# 2. Install dependencies
composer install --optimize-autoloader --no-dev

# 3. Configure environment
cp .env.example .env
nano .env    # Fill in APP_URL and DB_ settings

# 4. Generate key, run migrations, seed admin user
php artisan key:generate
php artisan migrate --seed

# 5. Create storage symlink
php artisan storage:link

# 6. Cache for performance
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 7. Set permissions
chmod -R 775 storage bootstrap/cache
```

Default admin credentials created by seeder:
- Email: `admin@election.local`
- Password: `Admin@123456`
> **Change this immediately after first login!**

---

## Troubleshooting

### "Composer not found" during install
- Upload `composer.phar` to the project root (download from https://getcomposer.org/download/)
- The installer will automatically detect and use it

### Storage link fails
Run manually via cPanel Terminal:
```bash
php artisan storage:link
```
Or create the symlink manually:
```bash
ln -s /home/user/public_html/election/storage/app/public /home/user/public_html/election/public/storage
```

### White page / 500 error
1. Temporarily set `APP_DEBUG=true` in `.env`
2. Check `storage/logs/laravel.log`
3. Ensure `storage/` and `bootstrap/cache/` are writable (chmod 775)

### "Migration failed" error
- Verify database credentials in `.env`
- Ensure the database exists in cPanel → MySQL Databases
- Ensure the DB user has ALL PRIVILEGES on the database

### Images/files not loading (404)
```bash
php artisan storage:link
```

### Session not working / can't stay logged in
- Ensure `storage/framework/sessions/` is writable
- Check `SESSION_DRIVER=file` in `.env`

### Excel import fails
- Ensure columns in your file are exactly: `full_name`, `telephone`, `unique_id`
- Use the provided `voter_import_template.csv` as reference
- Supported formats: `.xlsx`, `.xls`, `.csv`

---

## System Overview

### URLs After Installation
| URL | Purpose |
|-----|---------|
| `/` | Redirects to manifesto page |
| `/manifesto` | Public candidate profiles & manifestos |
| `/vote` | Voter login & ballot submission |
| `/admin` | Admin panel (Filament) |
| `/admin/elections` | Manage elections |
| `/admin/positions` | Manage positions |
| `/admin/candidates` | Manage candidates |
| `/admin/voters` | Manage & import voters |
| `/admin/audit-logs` | Security audit trail |
| `/admin/live-dashboard` | Real-time vote monitoring |
| `/admin/reports` | Download PDF/Excel reports |

### Admin Workflow
1. **Create Election** → set manifesto and voting date ranges
2. **Create Positions** → President, Secretary, Treasurer, etc.
3. **Add Candidates** → photo, manifesto PDF, biography, campaign message
4. **Import Voters** → upload Excel/CSV with full_name, telephone, unique_id
5. **Activate Election** → set status to "Active"
6. **Monitor Live** → Admin → Live Dashboard (auto-refreshes)
7. **Download Reports** → Results, Voter Turnout, Audit Log (PDF + Excel)
8. **Publish Results** → toggle "Publish Results" on the election record

### Voter Workflow
1. Visit `https://yourdomain.com/vote`
2. Enter Unique ID + telephone number
3. View ballot (one candidate per position)
4. Submit — system locks voter from re-voting
5. See success confirmation

---

## Security Features
- ✅ One vote per voter (database-level UNIQUE constraint)
- ✅ Votes cannot be edited or deleted after submission
- ✅ Admin cannot vote on behalf of voters
- ✅ All actions logged (voter logins, failed attempts, vote casts, admin actions)
- ✅ Elections automatically lock after voting period ends
- ✅ Results only visible publicly when admin "Publishes" them
- ✅ CSRF protection on all forms
- ✅ SQL injection protection via Eloquent ORM
- ✅ Encrypted sessions (AES-256-CBC)
- ✅ Installer self-locks and should be deleted after use

---

## Server Requirements
| Requirement | Minimum |
|------------|---------|
| PHP | 8.2+ |
| MySQL | 8.0+ (or MariaDB 10.4+) |
| Extensions | pdo, pdo_mysql, mbstring, openssl, tokenizer, xml, ctype, json |
| Extensions (optional) | gd (for PDF images), zip, bcmath |
| Disk space | 200MB+ (after composer install) |
| cPanel | Standard hosting with PHP 8.2 selector |