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

WordPress Development Environment

Status: Active/Authoritative Last Updated: March 26, 2025 Scope: Development environment setup and configuration

This is a Docker-based development environment for WordPress that replicates the production environment on Cloudways. It includes WordPress with PHP 8.1, MariaDB, and phpMyAdmin.

Prerequisites

• Docker and Docker Compose
• Git
• Node.js and npm (for E2E tests)
• mkcert (for SSL support, installed automatically if needed)

Environment Setup

1. Configuration

The .env file contains:

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

# 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

Testing

Refer to the comprehensive Testing Guide for detailed instructions on setting up the test environment, running different test suites (Unit, Integration, E2E), writing tests, and troubleshooting.

Quick Commands:

# 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

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

Common Issues

1. Environment Issues

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

2. Database Issues

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

3. Backup Issues

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

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