upskill-event-manager/wordpress-dev/DEPLOYMENT_GUIDE.md

# HVAC Community Events Plugin - Deployment Guide

## Overview

This guide provides comprehensive instructions for deploying, verifying, and troubleshooting the HVAC Community Events plugin on the staging and production environments.

## Deployment Scripts

### Primary Deployment Script

**Location**: `/wordpress-dev/staging-deployment/deploy-to-staging.sh`

This is the main deployment script that should be used for all plugin deployments.

**Usage**:
```bash
cd /path/to/wordpress-dev/staging-deployment
./deploy-to-staging.sh
```

**What it does**:
1. Creates backup of existing plugin on server
2. Uploads deployment package (`hvac-community-events-final-fixes.zip`)
3. Extracts and installs plugin files with proper permissions
4. Clears WordPress and Breeze caches
5. **Deactivates and reactivates plugin** (triggers page creation)
6. Flushes rewrite rules
7. Verifies plugin activation and page creation
8. Reports deployment status

### Alternative Deployment Script

**Location**: `/wordpress-dev/deploy-plugin-fixes-complete.sh`

Comprehensive deployment script with enhanced verification.

**Usage**:
```bash
cd /path/to/wordpress-dev
./deploy-plugin-fixes-complete.sh
```

**Features**:
- Automatic package creation with timestamp
- Enhanced error handling
- Integrated URL testing
- Comprehensive verification

## Verification Scripts

### Primary Verification Script

**Location**: `/wordpress-dev/verify-plugin-fixes.sh`

**Usage**:
```bash
cd /path/to/wordpress-dev
./verify-plugin-fixes.sh
```

**Verification Steps**:
1. **Remote URL Testing** - Tests all key URLs for accessibility
2. **E2E Testing** - Runs Playwright tests if available
3. **Screenshot Analysis** - Checks for generated screenshots
4. **Specific Fix Verification** - Tests individual fixes

### Remote URL Testing Script

**Location**: `/wordpress-dev/test-remote-fixes.js`

**Usage**:
```bash
cd /path/to/wordpress-dev
node test-remote-fixes.js
```

**Tests**:
- All trainer pages accessibility
- Legacy URL redirects
- Authentication flow
- Certificate reports functionality

## Configuration

### Environment Variables

**Location**: `/wordpress-dev/.env`

Required variables:
```bash
UPSKILL_STAGING_IP=146.190.76.204
UPSKILL_STAGING_SSH_USER=roodev
UPSKILL_STAGING_PASS=uSCO6f1y
UPSKILL_STAGING_PATH=/home/974670.cloudwaysapps.com/uberrxmprk/public_html
```

### Staging Server Details

- **Server**: 146.190.76.204
- **SSH User**: roodev
- **Path**: `/home/974670.cloudwaysapps.com/uberrxmprk/public_html`
- **Plugin Path**: `wp-content/plugins/hvac-community-events`
- **Backup Path**: `wp-content/plugins/hvac-backups`

## Step-by-Step Deployment Process

### 1. Pre-Deployment Preparation

```bash
# Navigate to staging deployment directory
cd /path/to/wordpress-dev/staging-deployment

# Verify all fixes are in place
ls -la hvac-community-events.php
ls -la includes/
ls -la templates/

# Check package exists
ls -la hvac-community-events-final-fixes.zip
```

### 2. Deploy Plugin

```bash
# Run deployment script
./deploy-to-staging.sh
```

**Expected Output**:
```
=== HVAC Community Events Deployment Script ===
✅ Backup created successfully
✅ Plugin files installed successfully
✅ Plugin activated successfully
✅ Login page exists
✅ Certificate reports page exists
=== Deployment Complete! ===
```

### 3. Verify Deployment

```bash
# Navigate back to main directory
cd ..

# Run verification
./verify-plugin-fixes.sh
```

**Expected Results**:
- Pages accessible: 80-100%
- Redirects working: 100%
- Overall success: 85-100%

### 4. Test Key URLs

Manually test these URLs:
- https://upskill-staging.measurequick.com/training-login/
- https://upskill-staging.measurequick.com/trainer/certificate-reports/
- https://upskill-staging.measurequick.com/hvac-dashboard/ (legacy redirect)
- https://upskill-staging.measurequick.com/trainer/dashboard/

## Troubleshooting Guide

### Common Issues and Solutions

#### 1. Plugin Activation Fails

**Symptom**: Plugin shows as inactive after deployment
**Solution**:
```bash
# SSH into server
ssh roodev@146.190.76.204

# Navigate to WordPress directory
cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html

# Manually activate plugin
wp plugin activate hvac-community-events --allow-root

# Check for errors
wp plugin list --allow-root
```

#### 2. Certificate Reports Still Shows 404

**Symptom**: `/trainer/certificate-reports/` returns 404 error
**Root Cause**: Pages not created during activation
**Solution**:
```bash
# Deactivate and reactivate plugin
wp plugin deactivate hvac-community-events --allow-root
wp plugin activate hvac-community-events --allow-root

# Flush rewrite rules
wp rewrite flush --allow-root

# Verify pages exist
wp post list --post_type=page --name=certificate-reports --allow-root
```

#### 3. Legacy Redirects Not Working

**Symptom**: `/hvac-dashboard/` doesn't redirect to `/trainer/dashboard/`
**Root Cause**: Redirect hooks not properly registered
**Solution**:
1. Check plugin activation
2. Clear all caches
3. Verify redirect code is in main plugin file

#### 4. Cache Issues

**Symptom**: Changes not visible on frontend
**Solution**:
```bash
# Clear WordPress cache
wp cache flush --allow-root

# Clear Breeze cache (if available)
wp breeze purge --cache=all --allow-root

# Clear object cache
wp cache delete --all --allow-root
```

#### 5. Permission Issues

**Symptom**: File permission errors during deployment
**Solution**:
```bash
# Set proper permissions on server
find wp-content/plugins/hvac-community-events -type d -exec chmod 755 {} \;
find wp-content/plugins/hvac-community-events -type f -exec chmod 644 {} \;
```

### Rollback Procedure

If deployment fails:

```bash
# SSH into server
ssh roodev@146.190.76.204
cd /home/974670.cloudwaysapps.com/uberrxmprk/public_html

# Find backup
ls wp-content/plugins/hvac-backups/

# Restore backup (replace [timestamp] with actual timestamp)
rm -rf wp-content/plugins/hvac-community-events
cp -r wp-content/plugins/hvac-backups/hvac-community-events-backup-[timestamp] wp-content/plugins/hvac-community-events

# Reactivate plugin
wp plugin activate hvac-community-events --allow-root
wp cache flush --allow-root
```

### Debugging Commands

```bash
# Check plugin status
wp plugin list --status=active --allow-root

# Check pages
wp post list --post_type=page --format=table --allow-root

# Check for PHP errors
tail -f /path/to/error.log

# Test specific URL
curl -I https://upskill-staging.measurequick.com/trainer/certificate-reports/
```

## E2E Testing

### Running Playwright Tests

```bash
cd /path/to/wordpress-dev

# Run comprehensive tests
npx playwright test comprehensive-plugin-tests.spec.ts

# Run fix verification tests
npx playwright test test-fixes-verification.spec.ts

# Run with UI for debugging
npx playwright test --ui
```

### Test Coverage

Tests verify:
- All plugin pages load correctly
- Authentication redirects work
- Legacy URL redirects function
- Form submissions work
- Navigation between pages
- Visual appearance via screenshots

## Maintenance

### Regular Checks

1. **Monthly**: Run verification script
2. **After updates**: Full deployment and testing
3. **Before production**: Complete E2E test suite

### Monitoring

Key metrics to monitor:
- Plugin activation status
- Page accessibility (should be 90%+ success rate)
- Redirect functionality (should be 100%)
- Error logs for PHP errors

## Quick Reference

### Deployment Checklist

- [ ] Source files ready in `staging-deployment/`
- [ ] Environment variables configured
- [ ] Backup space available on server
- [ ] Run deployment script
- [ ] Verify plugin activation
- [ ] Test key URLs manually
- [ ] Run verification script
- [ ] Check E2E test results

### Emergency Contacts

- **Staging Server**: 146.190.76.204
- **WordPress Path**: `/home/974670.cloudwaysapps.com/uberrxmprk/public_html`
- **Plugin Owner**: Ben Reed (`ben@tealmaker.com`)

### Important URLs

- **Staging Site**: https://upskill-staging.measurequick.com/
- **Login**: https://upskill-staging.measurequick.com/training-login/
- **Admin**: https://upskill-staging.measurequick.com/wp-admin/

---

*Last Updated: 2025-06-17*
*Version: 2.0*