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

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

```bash
# Stop and remove containers
docker-compose down

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

### Step 3: Check for Existing Backups

```bash
# List available backups
ls -la backups/
```

If no backups are available, create one:

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

### Step 4: Set Up Using the New Workflow

```bash
# 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`:
```bash
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
```bash
# Deploy configuration to staging
./bin/deploy-config-staging.sh

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

### Step 3: Configure Test Environment
```bash
# 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:
```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

### Development Environment Issues

#### "No backup found in backups/ directory!"

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

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

```bash
# 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](README.md) - Updated documentation for the development environment
- [bin/obsolete/README.md](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*