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:

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:

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:

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:

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:

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

# 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

# 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

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

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

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

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

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

# 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

# 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

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