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

Migration Guide: Staging Environment Workflows

Status: Active/Authoritative Last Updated: April 23, 2025 Scope: Transition to Cloudways staging environment workflow

This guide helps you transition to the Cloudways staging environment workflow, focusing on staging server integration and testing.

Overview of Changes

Staging Environment Integration

The staging environment workflow is now the primary development and testing approach:

Staging Workflow

deploy-config-staging.sh → configure-staging-tests.sh → run-staging-tests.sh

Staging Sync Workflow

sync-staging.sh → deploy-plugin.sh

Why the Change?

1. More Reliable: The Cloudways staging environment provides a production-like platform for testing
2. Faster Setup: Direct access to the staging environment eliminates local setup time
3. Consistent Environment: Everyone uses the same staging environment, ensuring consistent testing results
4. Simplified Workflow: No need to maintain local development environments

Migration Steps

Step 1: Update Your Repository

# Pull the latest changes
git pull

# Make sure you have the new scripts
ls -la bin/deploy-config-staging.sh

Step 2: Configure Environment Variables

Add staging credentials to .env:

UPSKILL_STAGING_URL=https://upskill-staging.measurequick.com/
UPSKILL_STAGING_IP=146.190.76.204
UPSKILL_STAGING_SSH_USER=roodev
UPSKILL_STAGING_PASS=<password>
UPSKILL_STAGING_PATH=/home/974670.cloudwaysapps.com/uberrxmprk/public_html
UPSKILL_STAGING_DB_NAME=uberrxmprk
UPSKILL_STAGING_DB_USER=uberrxmprk
UPSKILL_STAGING_DB_PASSWORD=<password>

Step 3: Deploy Configuration

# Deploy configuration to staging
./bin/deploy-config-staging.sh

# Verify deployment
./bin/verify-staging.sh

Step 4: Configure Test Environment

# Set up test configuration
./bin/configure-staging-tests.sh

# Run tests to verify setup
./bin/run-staging-unit-tests.sh

Step 5: Set up Test User

A test user with the 'hvac_trainer' role is required for running the E2E tests. Create this user on the staging environment using the ./bin/setup-staging-test-users.sh script.

Execute the script from the wordpress-dev/ directory after the HVAC Community Events plugin has been deployed and activated:

./bin/setup-staging-test-users.sh

The script creates a user with the username test_trainer and password from environment variables.

Script Reference

Staging Environment Scripts

Script	Purpose	Notes
configure-staging-tests.sh	Set up test environment	Creates test configuration files
deploy-config-staging.sh	Deploy configuration	Updates staging server config
deploy-plugin.sh	Deploy plugin code	Uploads plugin files to staging
run-staging-unit-tests.sh	Run unit tests	Executes tests on staging
run-staging-tests.sh	Run all tests	Runs unit, integration, and E2E tests
verify-staging.sh	Verify environment	Checks staging configuration
sync-staging.sh	Sync from staging	Downloads staging data

PHPUnit Test Configuration

The staging environment includes PHPUnit test configuration with:

1. Vendor-based PHPUnit installation (via Composer)
2. Staging-specific bootstrap file (tests/bootstrap-staging.php)
3. Custom test execution script (bin/run-staging-unit-tests.sh)

To verify the test configuration:

# Check PHPUnit version
./bin/run-staging-unit-tests.sh --version

# Run all tests
./bin/run-staging-unit-tests.sh

# Run specific test group
./bin/run-staging-unit-tests.sh --group=integration

Test configuration files:

• phpunit-staging.xml (main configuration)
• wp-tests-config-staging.php (WordPress test config)
• bootstrap-staging.php (test environment setup)

Common Issues and Solutions

"Cannot connect to staging server"

# Test SSH connection
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "echo 'Connection successful'"

# Verify environment variables
env | grep UPSKILL_STAGING

"Database connection issues"

# Test database connection
mysql -h "$UPSKILL_STAGING_IP" -u "$UPSKILL_STAGING_DB_USER" -p"$UPSKILL_STAGING_DB_PASSWORD" "$UPSKILL_STAGING_DB_NAME" -e "SELECT 1"

# Check database credentials
./bin/verify-staging.sh --database

"WordPress is not accessible"

# Check if WordPress is accessible
curl -I "$UPSKILL_STAGING_URL"

# Check WordPress status via SSH
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "cd $UPSKILL_STAGING_PATH && wp core is-installed"

"Test environment issues"

# Reconfigure test environment
./bin/configure-staging-tests.sh

# Check test configuration
./bin/verify-staging.sh --test-env

# View test logs
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f $UPSKILL_STAGING_PATH/wp-content/debug.log"

Best Practices for Staging Environment

1. Always verify your changes on staging before deploying to production
2. Run the full test suite after making significant changes
3. Keep the staging environment as close to production as possible
4. Use the Cloudways dashboard for server management tasks
5. Regularly sync data from production to staging to ensure testing with current data

Additional Resources

• README.md - Updated documentation for the staging environment
• docs/staging-phpunit-setup.md - Detailed PHPUnit configuration
• Cloudways Documentation - Official Cloudways support documentation

Support

If you encounter any issues with the staging workflow, please contact:

• Email: support@tealmaker.com
• Slack: #network-events-support

Last Updated: April 23, 2025