tomsjavajive-app/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

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

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)

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):

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
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
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