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

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

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

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

### Step 4: Configure Test Environment

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

```bash
./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:
```bash
# 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"

```bash
# 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"

```bash
# 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"

```bash
# 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"

```bash
# 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](README.md) - Updated documentation for the staging environment
- [docs/staging-phpunit-setup.md](docs/staging-phpunit-setup.md) - Detailed PHPUnit configuration
- [Cloudways Documentation](https://support.cloudways.com/en/) - 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*