# VulaPrize + VulaPulse — Pure PHP + phpMyAdmin cPanel Installation

This package is **strictly PHP + MySQL/MariaDB + phpMyAdmin**. It is not Laravel, not PostgreSQL, and does not require Node.js.

## 1. What you upload

Upload the folder contents so the server layout is:

```text
/home/CPANEL_USER/
├── public_html/
│   ├── index.php
│   ├── .htaccess
│   ├── assets/
│   └── media/
└── vulaprize-app/
    ├── app/
    ├── bootstrap/
    ├── database/
    ├── resources/
    ├── routes/
    ├── storage/
    ├── cron/
    ├── bin/
    └── .env
```

Keep `vulaprize-app` **outside** `public_html` whenever possible. Only `public_html` should be browser-accessible.

## 2. Create the database in cPanel

In cPanel, open **MySQL Databases**.

Create or confirm:

Use the full database name and username displayed by cPanel. They commonly include your cPanel account prefix, for example `accountname_vulaprize` and `accountname_dbuser`. Assign the user to the database and grant **ALL PRIVILEGES**.

> Never place the live database password in the ZIP or in public chat. Enter it directly into the private one-time installer after upload.

## 3. Install the database automatically

Open `https://your-domain.co.za/setup.php`. Enter the database host, port, full database name, full database username and password. The installer connects to the database and imports `vulaprize-app/database/schema.sql` automatically when the database is empty. If the database already has every required table, it will reuse the schema without dropping data. If it finds a partially installed database, it stops and explains the problem instead of deleting tables.

You do not need to use phpMyAdmin to import SQL for a normal fresh installation. The `install.sql` file remains available for manual recovery and DBA workflows.

The schema creates all system tables required for:

- Users
- Sessions
- Login attempts
- Contests
- Contest media
- Entries
- Entry entitlements
- Orders
- Payment callbacks
- KW transactions
- Daily streaks
- Redemptions
- Vouchers
- Support tickets
- Email queue
- Admin settings
- Audit logs
- Cron locks

## 4. Private configuration and Root Admin

The setup wizard writes `vulaprize-app/.env` outside `public_html` and generates a unique `APP_KEY`. It also creates the first Root Admin using the credentials you submit. Do not create a second `.env` manually or share database credentials in public. If you need to change credentials later, edit the private `.env` file through cPanel File Manager.

The installer generates the environment file and unique app key automatically. It sets `APP_DEBUG=false` and `REAL_MONEY_ENABLED=false`. The live database password is stored only in the private `.env` file outside `public_html`.

## 5. File permissions

Recommended permissions:

```text
folders: 755
files:   644
storage/: writable by PHP
public_html/media/contest-public/: writable by PHP
```

Make sure these are writable:

```text
vulaprize-app/storage/logs
vulaprize-app/storage/sessions
vulaprize-app/storage/uploads
vulaprize-app/storage/cache
vulaprize-app/storage/private
public_html/media/contest-public
```

## 6. Test the installation

Run:

```bash
cd /home/CPANEL_USER/vulaprize-app
php bin/check-install.php
```

Then open:

```text
https://your-domain.co.za/
https://your-domain.co.za/login
https://your-domain.co.za/admin
```

## 7. Cron jobs

In cPanel > Cron Jobs, add these commands.

Replace `/home/CPANEL_USER` with your real cPanel home path.

```bash
*/5 * * * * /usr/local/bin/php /home/CPANEL_USER/vulaprize-app/cron/close-contests.php >/dev/null 2>&1
*/10 * * * * /usr/local/bin/php /home/CPANEL_USER/vulaprize-app/cron/expire-orders.php >/dev/null 2>&1
*/15 * * * * /usr/local/bin/php /home/CPANEL_USER/vulaprize-app/cron/expire-entitlements.php >/dev/null 2>&1
*/15 * * * * /usr/local/bin/php /home/CPANEL_USER/vulaprize-app/cron/process-email-queue.php >/dev/null 2>&1
0 3 * * * /usr/local/bin/php /home/CPANEL_USER/vulaprize-app/cron/maintenance.php >/dev/null 2>&1
```

Some cPanel servers use versioned PHP paths like:

```bash
/opt/cpanel/ea-php83/root/usr/bin/php
```

Use the PHP path shown in cPanel.

## 8. Payment safety

The system ships with:

```dotenv
REAL_MONEY_ENABLED=false
```

Keep this disabled until:

- Terms are legally reviewed
- POPIA/privacy notice is reviewed
- PayFast sandbox works
- Webhook/ITN validation is tested
- Refund and dispute process is defined
- Production gateway credentials are inserted

## 9. Colours and branding included

The UI uses the official VulaPrize palette:

```css
--vula-navy: #0A1E3F;
--vula-amber: #F5A623;
--vula-teal: #00B894;
--vula-ruby: #E63946;
--vula-gold: #FFD700;
--vula-cloud: #F8F9FA;
--vula-slate: #2C3E50;
--vula-charcoal: #2D3748;
--vula-mist: #F0F4F8;
```

The package includes:

- Splash loader
- Glitch text effect
- Liquid text styling
- Countdown cards
- VulaPulse KW styling
- Client/admin branded interface
- Official colour-mapped buttons and badges

## 10. Important security note

After installation, remove `public_html/setup.php`. Rotate any database password that may have been exposed outside a private configuration channel, and update the private `.env` file.