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

WordPress Development & Staging Environments

Status: Active/Authoritative Last Updated: April 23, 2025 Scope: Development and staging environment setup and configuration

This repository contains configuration and tools for the Cloudways staging environment. The staging environment provides a production-like testing platform for development, testing, and deployment validation. Local Docker-based development is no longer supported; all development and testing should be performed using the Cloudways staging server.

Environment Overview

Staging Environment (Cloudways)

• Production-like environment for all development, testing, and deployment validation

• No local server or Docker-based development is supported

• SSH access to Cloudways server is required

• Use sshpass for automated scripts (optional)

• MySQL client for database operations

• All environment variables must be set in .env:

  UPSKILL_STAGING_URL=https://wordpress-974670-5399585.cloudwaysapps.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>
  

Staging Environment Setup

1. Configuration

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

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

2. Testing Setup

# Configure test environment on staging
./bin/configure-staging-tests.sh

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

3. Test User Setup

A test user with the 'hvac_trainer' role is required for running the E2E tests that cover trainer-specific workflows. This user can be created 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 on the staging server:

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

The script creates a user with the username test_trainer and password Test123!.

3. Data Synchronization

# Sync data from staging to local backup
./bin/sync-staging.sh

# Deploy local changes to staging
./bin/deploy-plugin.sh

Environment Setup

1. Configuration

The .env file contains:

• Staging server details
• Database credentials
• WordPress authentication
• SSL configuration
• Development settings

Important: Ensure the PHP memory_limit is set sufficiently high (e.g., 512M) in the Cloudways PHP settings via the Cloudways dashboard.

2. Creating New Backups

If you need to create a new backup from production:

# Create a new backup from production
./bin/sync-production-fixed.sh

This will create a new backup in the backups/ directory with the current date and time.

3. Plugin Setup

Required plugins are included in the backups:

• The Events Calendar Suite (6.10.2+)
• Event Tickets Suite (5.19.3+)
• Additional required plugins

4. Automatic Page Creation

Upon activation, the HVAC Community Events plugin automatically creates the following required pages if they don't already exist:

• Community Login (/community-login/)
• Trainer Registration (/trainer-registration/)
• Trainer Dashboard (/hvac-dashboard/)

Ensure the plugin is deactivated and reactivated if these pages are missing after setup.

Access Points

• WordPress Site:
  • URL: https://wordpress-974670-5399585.cloudwaysapps.com/
• WordPress Admin:
  • URL: https://wordpress-974670-5399585.cloudwaysapps.com/wp-admin/
• Database Access:
  • Via Cloudways dashboard or MySQL client using the credentials in .env

Development Tools

Syncing Data from Staging

To sync data from the staging server to your local backup directory:

./bin/sync-staging.sh

This script will download WordPress files and a database dump from the staging server, storing them in the backups/ directory.

PHPUnit Testing

PHPUnit is configured for the staging environment:

# Run PHPUnit tests on staging
./bin/run-staging-unit-tests.sh

# Run specific test suite
./bin/run-staging-unit-tests.sh --testsuite unit

# Run tests with coverage report
./bin/run-staging-unit-tests.sh --coverage-html ./coverage-report

Refer to staging-phpunit-setup.md for detailed configuration.

Testing

Refer to the comprehensive Testing Guide for detailed instructions on setting up test environments, running test suites, writing tests, and troubleshooting.

E2E Tests:

# Run E2E tests targeting the staging environment
./bin/run-tests.sh --e2e

Note: The E2E tests are executed locally using this command from the `wordpress-dev/` directory and target the staging environment as configured in `playwright.config.ts`. The command `./tests/run-tests.sh pw` is outdated and should not be used.

Staging Environment Tests:

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

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

# Run all test suites on staging
./bin/run-staging-tests.sh

# Run specific test on staging
./bin/run-staging-unit-tests.sh --filter=test_get_total_events_count

Important Notes:

• Some tests may be skipped in staging due to environment differences
• E2E tests target the staging URL defined in .env
• Database operations use staging credentials
• File paths must match staging server structure

WP-CLI

WP-CLI is available on the staging server via SSH:

# Run WP-CLI commands on staging
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "cd $UPSKILL_STAGING_PATH && wp plugin list"

Database Operations

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

# Verify database configuration
./bin/verify-staging.sh --database

Logs and Monitoring

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

# View PHP error logs
sshpass -p "$UPSKILL_STAGING_PASS" ssh "$UPSKILL_STAGING_SSH_USER@$UPSKILL_STAGING_IP" "tail -f /var/log/php-fpm/www-error.log"

Troubleshooting

Staging Environment Issues

1. SSH Connection Issues

   # 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
   

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

3. Test Environment Issues

   # Reconfigure test environment
   ./bin/configure-staging-tests.sh
   
   # Check test configuration
   ./bin/verify-staging.sh
   
   # 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"
   

4. Deployment Issues

   # Verify file permissions
   ./bin/verify-staging.sh --permissions
   
   # Deploy configuration
   ./bin/deploy-config-staging.sh
   
   # Check deployment status
   ./bin/verify-staging.sh --deployment
   

5. Backup Issues

   # Check available backups
   ls -la backups/
   
   # Create a new backup
   ./bin/sync-production-fixed.sh
   

6. WordPress Access Issues

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

Debug Mode

WordPress debug mode is enabled by default in the staging environment. Debug logs can be viewed with:

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

Common Staging Problems and Solutions

Problem	Solution
Search Engine Indexing	Use robots.txt file or meta tags to prevent staging site indexing
Staging Sites Sending Emails	Configure email redirection to prevent staging emails going to customers
Problems with Licensing	Check software provider's licensing policies for staging environments
Overwriting Live Data	Use selective push/pull to avoid overwriting critical data

Best Practices for Staging Sites

1. Take full backups before making significant changes
2. Clear cache when changing code
3. Keep production database separate from testing database
4. Restrict public access to staging environment
5. Use staging-specific configuration for sensitive services

Security Notes

1. Never commit .env to version control
2. Use WordPress Application Passwords for API access
3. Keep production credentials secure
4. Regularly rotate passwords and tokens
5. Keep SSL certificates secure

Support

For issues:

1. Check debug logs
2. Review server logs
3. Verify environment configuration
4. Contact development team:
   • Email: support@tealmaker.com
   • Slack: #network-events-support

Last Updated: April 23, 2025