# Installation Guide

Fresh installation of JMS Radio, Podcast & Campus Media Hub on shared hosting (cPanel). For upgrades from a previous phase, use the per-phase delta SQLs — this guide is for new deployments only.

## Requirements

| | Minimum | Notes |
|---|---|---|
| PHP | 8.0+ | PDO, PDO_MySQL, openssl, curl, gd, mbstring, json required |
| MySQL / MariaDB | 5.7+ / 10.4+ | InnoDB engine required |
| Apache | 2.4+ | mod_rewrite, mod_expires, mod_deflate |
| HTTPS | Required | Push notifications and PWA service workers require HTTPS |
| Disk | 500 MB+ | For uploaded audio reports, images, cover art |

---

## Step 1 — Upload files

1. Extract the Phase 10 ZIP locally.
2. Connect via FTP (FileZilla) or cPanel File Manager.
3. Upload the **contents** of `public_html/` to your web root. Include `.htaccess` — enable "Show hidden files" in FileZilla (Server → Force showing hidden files).
4. Do NOT upload `database/` or `docs/` to the web root.

---

## Step 2 — Create the MySQL database

1. cPanel → MySQL Databases → create a new database (e.g. `user_jmsdb`).
2. Create a new user (e.g. `user_jmsapp`) with a strong password.
3. Grant ALL PRIVILEGES on the new database to the new user.

---

## Step 3 — Import the schema

1. cPanel → phpMyAdmin → select your new database.
2. Click Import → choose `database/schema.sql` → Go.

This creates all 25 tables and seeds required data (categories, AI tool settings, radio_status singleton row).

---

## Step 4 — Configure the application

Copy `config/config.sample.php` to `config/config.php` and fill in all values:

```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'user_jmsdb');
define('DB_USER', 'user_jmsapp');
define('DB_PASS', 'your_strong_password');

define('SITE_NAME', 'JMS Media Hub');
define('SITE_URL',  'https://your-domain.example'); // no trailing slash
define('FORCE_HTTPS', true);
define('APP_DEBUG', false);

// Generate with: php -r "echo bin2hex(random_bytes(24));"
define('APP_SECRET', 'long-random-string-here');
define('SETUP_KEY',  'different-long-random-string-here');

define('MAIL_DRIVER',     'smtp');
define('MAIL_FROM_EMAIL', 'noreply@your-domain.example');
define('MAIL_FROM_NAME',  'JMS Media Hub');
define('SMTP_HOST',       'smtp.your-provider.example');
define('SMTP_PORT',       587);
define('SMTP_USER',       'noreply@your-domain.example');
define('SMTP_PASS',       'smtp_password');
define('SMTP_ENCRYPTION', 'tls');
```

---

## Step 5 — Create the first admin account

Visit `https://your-domain.example/setup/install.php?key=YOUR_SETUP_KEY`, fill in the admin details, then **immediately delete** `public_html/setup/install.php`.

---

## Step 6 — Verify upload directories are writable

These must be writable by the web server (chmod 755):

```
public_html/uploads/profile-photos/
public_html/uploads/featured-images/
public_html/uploads/covers/
public_html/uploads/audio-reports/
```

cPanel File Manager → right-click folder → Change Permissions → 755.

---

## Step 7 — VAPID keys for push notifications (optional)

1. Run: `php public_html/setup/generate-vapid-keys.php` (CLI or browser with SETUP_KEY)
2. Paste the two key values into `config/config.php`
3. **Delete** `public_html/setup/generate-vapid-keys.php`

---

## Step 8 — AI tools API key (optional)

```php
define('CLAUDE_API_KEY', 'sk-ant-...');  // console.anthropic.com
```

---

## Step 9 — Sitemap cron job

cPanel → Cron Jobs:
- Command: `php /home/YOUR_CPANEL_USER/public_html/cron/generate-sitemap.php`
- Schedule: `0 2 * * *` (daily 2 AM)

Run once manually first: `https://your-domain.example/cron/generate-sitemap.php?key=YOUR_SETUP_KEY`

Submit `https://your-domain.example/sitemap.xml` to Google Search Console.

---

## Step 10 — Verify

1. Homepage loads with dark/light toggle working
2. Register as a student, verify the email link arrives
3. Submit a test article, approve it as an editor, confirm it appears on the homepage

---

## Troubleshooting

**Blank page / 500 error:** Set `APP_DEBUG = true` temporarily, reload, read the error, set back to `false`.

**Uploads failing:** Check upload directory permissions (chmod 755). Check `upload_max_filesize` in cPanel → MultiPHP INI Editor (must be ≥ 25MB for audio reports).

**Emails not arriving:** Use SMTP driver — most cPanel hosts block PHP's `mail()` for outbound delivery.

**Push notifications not working:** Confirm HTTPS is active, VAPID keys are set, service worker registered (DevTools → Application → Service Workers).

**AI tools returning errors:** Check the API key in `config.php` matches the provider in `admin/ai-tools-settings.php` and has available credits.