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

WordPress Development & Staging Environments

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

This repository contains configuration and tools for both local development (Docker-based) and staging (Cloudways) environments. The local environment includes WordPress with PHP 8.1, MariaDB, and phpMyAdmin, while the staging environment provides a production-like testing platform.

Environment Overview

Local Development

• There is no local server. Please use the staging server.

Staging (Cloudways)

• Production-like environment
• Limited configuration access
• Final testing platform
• Deployment validation

Prerequisites

Local Development

• There is no local server. Please use the staging server.

Staging Environment

• SSH access to Cloudways server
• sshpass (for automated scripts)
• MySQL client (for database operations)
• Environment variables 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. Data Synchronization

# Sync data from staging to local
./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 php.ini/custom.ini. Restart containers after changing this file (docker-compose down && docker-compose up -d).

2. Development Environment Setup from Backup

The recommended way to set up the development environment is using existing backups:

# Set up environment from the latest backup
./bin/setup-from-backup.sh

# Verify setup
./bin/verify-simple.sh

This process:

1. Uses the latest backup from the backups/ directory
2. Sets up the Docker containers (WordPress, MariaDB, phpMyAdmin, Nginx)
3. Imports the database from the backup
4. Updates site URLs to point to localhost:8080
5. Configures WordPress with the correct settings

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

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

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:
  • HTTP: http://localhost:8080
  • HTTPS: https://localhost:8443 (when SSL enabled)
• phpMyAdmin: http://localhost:8081
  • Server: db
  • Username: from .env (DEV_DB_USER)
  • Password: from .env (DEV_DB_PASSWORD)

Development Tools

Environment Management

Syncing Data from Staging

To sync data from the staging server to your local development environment, use the following command:

./bin/sync-staging.sh

This script will download WordPress files and a database dump from the staging server, storing them in the backups/ directory. The setup-from-backup.sh script will then use these files to set up your local development environment.

# Set up environment from backup
./bin/setup-from-backup.sh

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

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

# More detailed verification
./bin/verify-dev-fixed.sh

# Reset development environment
./bin/reset-dev.sh

# Setup SSL (if needed)
./bin/setup-ssl.sh

PHPUnit Testing

PHPUnit is configured for both local and staging environments:

# Run PHPUnit tests (vendor installation)
./vendor/bin/phpunit --bootstrap tests/bootstrap-staging.php

# Run specific test suite
./vendor/bin/phpunit --testsuite unit

# Run tests with coverage report
./vendor/bin/phpunit --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.

Local Development Tests:

# Run all tests (Unit, Integration, E2E)
./bin/run-tests.sh

# Run only Unit tests
./bin/run-tests.sh --unit

# Run only Integration tests
./bin/run-tests.sh --integration

# Run only E2E tests
./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 inside the wordpress container via a direct volume mount of the phar file. Use docker-compose exec and the --allow-root flag:

docker-compose exec wordpress wp plugin list --allow-root

Database Operations

# Manage database operations
./bin/manage-db-fixed.sh

# Reset development database
./bin/reset-dev.sh

Logs and Cleanup

# View logs
./bin/logs.sh

# Clean up environment
./bin/cleanup.sh

Troubleshooting

Local Environment Issues

1. Docker Environment Issues

   # Check container status
   docker-compose ps
   
   # View container logs
   docker-compose logs
   # or
   ./bin/logs.sh
   

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
   tail -f /home/974670.cloudwaysapps.com/uberrxmprk/public_html/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. Database Issues

   # Reset database
   ./bin/reset-dev.sh
   
   # Verify database connection
   ./bin/verify-simple.sh
   

6. Backup Issues

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

7. WordPress Access Issues

   # Check if WordPress is accessible
   curl -I http://localhost:8080
   
   # Restart containers
   docker-compose down && docker-compose up -d
   

Debug Mode

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

# View debug logs
docker-compose logs wordpress
# or
./bin/logs.sh wordpress

Migration Guide

If you were using the old setup scripts (setup-dev.sh, sync-production.sh), follow these steps to migrate to the new workflow:

1. Create a backup of your current development environment if needed
2. Pull the latest changes from the repository
3. Use the new setup-from-backup.sh script to set up your environment
4. If you need to create a new backup from production, use sync-production-fixed.sh

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 container logs
3. Verify environment configuration
4. Contact development team:
   • Email: support@tealmaker.com
   • Slack: #network-events-support

Last Updated: March 26, 2025