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

Migration Guide: Development & Staging Environment Workflows

Status: Active/Authoritative Last Updated: April 8, 2025 Scope: Transition to new development and staging workflows

This guide helps you transition to the new development and staging environment workflows, including the backup-based approach and staging server integration.

Overview of Changes

Development Environment Changes

The local development workflow now uses a backup-based approach:

Old Workflow

setup-dev.sh → sync-production.sh → verify-dev.sh

New Workflow

sync-production.sh → setup-from-backup.sh → verify-dev.sh

Staging Environment Integration

New staging environment workflow added:

Staging Workflow

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

Staging Sync Workflow

sync-staging.sh → setup-from-backup.sh → verify-dev.sh

Why the Change?

1. More Reliable: The new workflow uses existing backups, reducing the chance of errors during setup
2. Faster Setup: Setting up from a backup is faster than syncing directly from production
3. Offline Support: You can set up the environment without needing access to the production server
4. Consistent Environment: Everyone uses the same backup, ensuring consistent 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/setup-from-backup.sh

Step 2: Clean Up Your Current Environment (Optional)

If you want to start fresh:

# Stop and remove containers
docker-compose down

# Remove volumes (optional, will delete all data)
docker volume prune -f

Step 3: Check for Existing Backups

# List available backups
ls -la backups/

If no backups are available, create one:

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

Step 4: Set Up Using the New Workflow

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

# Verify the environment
./bin/verify-dev.sh

Script Mapping

Development Environment Scripts

Old Script	New Script	Notes
setup-dev.sh	setup-from-backup.sh	New script uses existing backups
sync-production.sh	sync-production.sh	Same name, updated implementation
verify-dev.sh	verify-dev.sh	Same name, updated implementation
sync-and-setup.sh	Use both scripts separately	Split into two separate steps

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

Staging Environment Setup

Step 1: Configure Environment Variables

Add staging credentials to .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>

Step 2: Deploy Configuration

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

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

Step 3: Configure Test Environment

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

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

PHPUnit Test Configuration

The staging environment now 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

Development Environment Issues

"No backup found in backups/ directory!"

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

"Cannot connect to production server"

You can still set up the environment if someone else has created a backup:

1. Get a backup from another developer
2. Place it in the backups/ directory
3. Run ./bin/setup-from-backup.sh

"Database connection issues"

# Check database container
docker-compose ps | grep db

# Restart containers
docker-compose down && docker-compose up -d

# Verify database connection
./bin/verify-simple.sh

"WordPress is not accessible"

# Check if WordPress container is running
docker-compose ps | grep wordpress

# Check WordPress logs
docker-compose logs wordpress

# Restart containers
docker-compose down && docker-compose up -d

Additional Resources

• README.md - Updated documentation for the development environment
• bin/obsolete/README.md - Information about obsolete scripts

Support

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

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

Last Updated: March 26, 2025