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

## Staging Environment Setup

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

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

### 2. Testing Setup
```bash
# Configure test environment on staging
./bin/configure-staging-tests.sh

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

### 3. Data Synchronization
```bash
# 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:

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

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

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

```bash
# 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](docs/staging-phpunit-setup.md) for detailed configuration.


### Testing

Refer to the comprehensive **[Testing Guide](./testing.md)** for detailed instructions on setting up test environments, running test suites, writing tests, and troubleshooting.

**Local Development Tests:**
```bash
# 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:**
```bash
# 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:
```bash
docker-compose exec wordpress wp plugin list --allow-root
```

### Database Operations

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

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

### Logs and Cleanup

```bash
# View logs
./bin/logs.sh

# Clean up environment
./bin/cleanup.sh
```

## Troubleshooting

### Local Environment Issues

1. **Docker Environment Issues**
   ```bash
   # Check container status
   docker-compose ps
   
   # View container logs
   docker-compose logs
   # or
   ./bin/logs.sh
   ```

### Staging Environment Issues

1. **SSH Connection Issues**
   ```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
   ```

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

3. **Test Environment Issues**
   ```bash
   # 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**
   ```bash
   # Verify file permissions
   ./bin/verify-staging.sh --permissions
   
   # Deploy configuration
   ./bin/deploy-config-staging.sh
   
   # Check deployment status
   ./bin/verify-staging.sh --deployment
   ```

2. **Database Issues**
   ```bash
   # Reset database
   ./bin/reset-dev.sh
   
   # Verify database connection
   ./bin/verify-simple.sh
   ```

3. **Backup Issues**
   ```bash
   # Check available backups
   ls -la backups/
   
   # Create a new backup
   ./bin/sync-production-fixed.sh
   ```

4. **WordPress Access Issues**
   ```bash
   # 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:

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