tomsjavajive/docs/DEPLOYMENT.md

# Tom's Java Jive - PHP/MySQL Deployment Guide

## cPanel FTP Deployment Instructions

This guide covers deploying Tom's Java Jive to a cPanel shared hosting environment with FTP access only (no SSH/root).

### Requirements

- PHP 8.4+ 
- MySQL 8.0+
- FTP Client (FileZilla, Cyberduck, etc.)
- cPanel access for database creation

---

## Step 1: Create MySQL Database in cPanel

1. Log into your cPanel dashboard
2. Navigate to **MySQL® Databases**
3. Create a new database:
   - Database name: `tomsjavajive` (or your preferred name)
   - Note the full database name (usually `cpaneluser_tomsjavajive`)
4. Create a database user:
   - Username: (your choice)
   - Password: (strong password)
5. Add user to database:
   - Select the user and database
   - Grant **ALL PRIVILEGES**
6. Note down your credentials:
   - Database host: `localhost` (usually)
   - Database name: (full name from step 3)
   - Username: (full username from step 4)
   - Password: (from step 4)

---

## Step 2: Configure Application Settings

### Edit `config/database.php`

```php
define('DB_HOST', 'localhost');
define('DB_NAME', 'cpaneluser_tomsjavajive');  // Your full database name
define('DB_USER', 'cpaneluser_dbuser');         // Your full database username
define('DB_PASS', 'your_secure_password');      // Your database password
```

### Edit `config/config.php`

```php
define('SITE_NAME', "Tom's Java Jive");
define('SITE_URL', 'https://yourdomain.com');  // Your actual domain
define('SITE_EMAIL', 'support@yourdomain.com');

// Set to 'production' for live site
define('ENVIRONMENT', 'production');
define('DEBUG_MODE', false);

// Stripe Keys (get from https://dashboard.stripe.com/apikeys)
define('STRIPE_SECRET_KEY', 'sk_live_xxxx');  // Use sk_test_ for testing
define('STRIPE_PUBLISHABLE_KEY', 'pk_live_xxxx');
define('STRIPE_WEBHOOK_SECRET', 'whsec_xxxx');

// SendGrid (get from https://app.sendgrid.com/settings/api_keys)
define('SENDGRID_API_KEY', 'SG.xxxx');
define('SENDER_EMAIL', 'noreply@yourdomain.com');

// Twilio (optional - get from https://www.twilio.com/console)
define('TWILIO_SID', '');
define('TWILIO_AUTH_TOKEN', '');
define('TWILIO_PHONE', '');
```

---

## Step 3: Upload Files via FTP

1. Connect to your server using FTP:
   - Host: Your domain or ftp.yourdomain.com
   - Port: 21 (or 22 for SFTP)
   - Username: Your cPanel username
   - Password: Your cPanel password

2. Navigate to `public_html` (or your web root)

3. Upload ALL files from the `tomsjavajive-php` folder:
   ```
   /public_html/
   ├── admin/
   ├── api/
   ├── assets/
   ├── account/
   ├── config/
   ├── docs/
   ├── includes/
   ├── install/
   ├── pages/
   ├── index.php
   ├── shop.php
   ├── product.php
   ├── cart.php
   ├── checkout.php
   ├── payment.php
   ├── login.php
   ├── register.php
   ├── logout.php
   └── ... (other files)
   ```

4. Set file permissions (via FTP client or cPanel File Manager):
   - All `.php` files: 644
   - All directories: 755
   - `uploads/` directory: 755 (create if not exists)
   - `config/` directory: 755

---

## Step 4: Import Database Schema

### Option A: Using phpMyAdmin (Recommended)

1. In cPanel, open **phpMyAdmin**
2. Select your database from the left sidebar
3. Click the **Import** tab
4. Click **Choose File** and select `install/schema.sql`
5. Click **Go** to execute

### Option B: Using MySQL command in cPanel Terminal (if available)

```bash
mysql -u cpaneluser_dbuser -p cpaneluser_tomsjavajive < install/schema.sql
```

---

## Step 5: Create First Admin User

After importing the schema, create your first admin user via phpMyAdmin:

1. Open phpMyAdmin
2. Select your database
3. Click the **SQL** tab
4. Run this query (replace with your details):

```sql
INSERT INTO admin_users (user_id, email, password_hash, name, is_admin, is_master, permissions)
VALUES (
    'admin_001',
    'admin@yourdomain.com',
    '$2y$12$xxxxx',  -- Generate bcrypt hash (see below)
    'Admin',
    1,
    1,
    '{"dashboard":true,"pos":true,"products":true,"orders":true,"customers":true,"settings_payment":true,"settings_shipping":true,"settings_email":true,"admin_management":true}'
);
```

**To generate password hash:**
Create a temporary PHP file called `generate_hash.php`:
```php
<?php
echo password_hash('YourSecurePassword123', PASSWORD_BCRYPT, ['cost' => 12]);
?>
```
Upload it, visit it in browser, copy the hash, then DELETE the file.

---

## Step 6: Configure Stripe Webhook (Optional but Recommended)

1. Go to [Stripe Dashboard > Webhooks](https://dashboard.stripe.com/webhooks)
2. Click **Add endpoint**
3. Set endpoint URL: `https://yourdomain.com/api/webhook.php`
4. Select events:
   - `payment_intent.succeeded`
   - `payment_intent.payment_failed`
   - `charge.refunded`
5. Copy the **Signing secret** to your `config.php`

---

## Step 7: Test Your Installation

1. Visit `https://yourdomain.com` - Should show storefront
2. Visit `https://yourdomain.com/admin/` - Should show admin login
3. Login with your admin credentials
4. Add a test product
5. Test the checkout flow

---

## Data Migration from MongoDB

If you have existing data in MongoDB that needs to be migrated:

### Prerequisites
- PHP with MongoDB extension (`pecl install mongodb`)
- Access to your MongoDB server

### Running Migration
The migration script is located at `install/migrate_from_mongodb.php`.

Since cPanel typically doesn't have MongoDB extension, you have two options:

**Option A: Export/Import Manually**
1. Export MongoDB collections to JSON using `mongoexport`
2. Convert and import to MySQL using phpMyAdmin or custom scripts

**Option B: Run Migration Locally**
1. Install PHP MongoDB extension locally
2. Connect to both databases
3. Run: `php migrate_from_mongodb.php [mongodb_url] [mongodb_dbname]`

---

## Security Checklist

Before going live:

- [ ] Change default admin password
- [ ] Update `SITE_URL` in config.php
- [ ] Set `ENVIRONMENT` to 'production'
- [ ] Set `DEBUG_MODE` to false
- [ ] Configure real Stripe keys (not test keys)
- [ ] Configure SendGrid for emails
- [ ] Delete `install/` folder after setup
- [ ] Set up SSL certificate (HTTPS)
- [ ] Enable Stripe webhook
- [ ] Test payment flow end-to-end

---

## Troubleshooting

### "Database connection failed"
- Check database credentials in `config/database.php`
- Verify database exists in cPanel
- Ensure user has privileges on the database

### "500 Internal Server Error"
- Check `.htaccess` file exists
- View error logs in cPanel > Error Log
- Temporarily enable `DEBUG_MODE` in config.php

### "Blank page"
- Enable PHP error display temporarily
- Check PHP version (requires 8.4+)
- View Apache/PHP error logs

### "Session errors"
- Ensure `session.save_path` is writable
- Check `sessions/` folder permissions

### "Payment not working"
- Verify Stripe keys are correct
- Check browser console for JS errors
- Verify webhook endpoint is accessible

---

## File Structure Reference

```
tomsjavajive-php/
├── admin/                  # Admin panel
│   ├── assets/            # Admin CSS/JS
│   ├── includes/          # Admin header/footer
│   ├── index.php          # Dashboard
│   ├── products.php       # Product management
│   ├── orders.php         # Order management
│   └── ...
├── api/                    # API endpoints
│   ├── cart.php
│   ├── products.php
│   ├── orders.php
│   └── webhook.php        # Stripe webhook
├── assets/                 # Public assets
│   ├── css/
│   ├── js/
│   └── images/
├── account/                # Customer account pages
├── config/                 # Configuration files
│   ├── config.php         # Main config
│   └── database.php       # DB credentials
├── includes/               # Shared includes
│   ├── auth.php
│   ├── db.php
│   ├── functions.php
│   ├── header.php
│   └── footer.php
├── install/                # Installation files
│   ├── schema.sql         # Database schema
│   └── migrate_from_mongodb.php
├── index.php              # Homepage
├── shop.php               # Shop page
├── product.php            # Product detail
├── cart.php               # Shopping cart
├── checkout.php           # Checkout
└── payment.php            # Stripe payment
```

---

## Support

For issues with this deployment:
1. Check the troubleshooting section above
2. Review error logs in cPanel
3. Verify all configuration values are correct

---

*Last updated: December 2025*
*PHP Version: 8.4.19 | MySQL Version: 8.0*