upskill-event-manager/docs/deployment.md

Deployment Guide

This guide covers deploying the HVAC Trainer Network Events plugin to development and production environments.

Quick Start

# Deploy to development
./Users/ben/dev/upskill-event-manager/wordpress-dev/deploy.sh --config deploy-config.sh

# Deploy and run tests
./Users/ben/dev/upskill-event-manager/wordpress-dev/deploy.sh --config deploy-config.sh --run-tests

# Deploy to production
./Users/ben/dev/upskill-event-manager/wordpress-dev/deploy.sh --config deploy-config-production.sh

Plugin Dependencies

The HVAC Trainer Network Events plugin requires the following plugins:

1. The Events Calendar (6.10.2 or higher)
2. The Events Calendar Pro (7.4.2 or higher)
3. Event Tickets (5.19.3 or higher)
4. Event Tickets Plus (6.2.0 or higher)
5. The Events Calendar: Community Events (latest version)
6. Spectra Pro (2.0.0 or higher)
7. Premium Starter Templates (4.4.14 or higher)
8. Essential Blocks (5.3.2 or higher)

Important Notes:

• Plugin versions are managed separately from deployment
• Do not update plugins as part of deployment or testing
• Plugin updates should be tested separately in a staging environment
• Use the plugin management system of your hosting environment for updates

Configuration Files

Development Configuration

File: deploy-config.sh

REMOTE_HOST="upskill_wordpress"
REMOTE_USER="root"
WP_PATH="/var/www/html/"
PLUGIN_SLUG="network-events"
WP_CLI_PATH="wp"
PURGE_BREEZE_CACHE=false
USE_ROOT=true

Production Configuration

File: deploy-config-production.sh

• Contains production-specific settings
• Includes additional security measures
• Requires SSH key configuration

Deployment Process

1. Pre-deployment Checks

   • Verify dependencies
   • Run tests
   • Check file permissions

2. Deployment Steps

   • Package plugin files
   • Transfer to target environment
   • Update WordPress configuration
   • Clear caches

3. Post-deployment Verification

   • Check plugin activation
   • Verify functionality
   • Monitor error logs

Development Environment (Cloudways Staging)

Note (April 7, 2025): The development strategy has shifted. The previous NAS-based Docker environment is paused/deprecated. Development and testing will now primarily occur on an official Cloudways staging environment.

The Cloudways staging environment aims to closely mirror the production setup. Deployment to staging and from staging to production will follow Cloudways-specific procedures.

Details regarding access, workflow, and testing on the Cloudways staging environment will be documented separately (TBD). The information below regarding the NAS setup is outdated.

Production Environment

Requirements

• SSH access to production server
• WordPress admin credentials
• Appropriate file permissions

Deployment Steps

1. Configure SSH access
2. Update production configuration
3. Run deployment script
4. Verify deployment

Troubleshooting

Common Issues

1. Permission Errors

   # Fix permissions
   # Permissions are typically set during setup/reset scripts.
   # If needed, check permissions inside containers via SSH:
   # ssh <user>@<nas_ip> "cd /path/to/project && /usr/local/bin/docker-compose exec wordpress stat /var/www/html"
   

2. Cache Issues

   # Clear WordPress cache
   # Use WP-CLI via SSH if needed:
   # ssh <user>@<nas_ip> "cd /path/to/project && /usr/local/bin/docker-compose exec wordpress wp cache flush --allow-root"
   

3. Plugin Activation Issues

   # Check plugin status
   # Use WP-CLI via SSH if needed:
   # ssh <user>@<nas_ip> "cd /path/to/project && /usr/local/bin/docker-compose exec wordpress wp plugin list --allow-root"
   

Rollback Procedure

If deployment fails:

1. Restore from backup
2. Revert plugin files
3. Clear caches
4. Verify functionality

Maintenance

Regular Tasks

1. Update dependencies
2. Run tests
3. Monitor error logs
4. Backup data

Backup Management

# Create backup (on NAS)
./wordpress-dev/bin/manage-db-fixed.sh backup

# Restore from backup (on NAS, specify relative path on NAS)
./wordpress-dev/bin/manage-db-fixed.sh restore backups/backup_file_name.sql

Security Considerations

1. Configuration Security

   • Use environment variables
   • Secure sensitive data
   • Restrict file permissions

2. Access Control

   • Limit SSH access
   • Use strong passwords
   • Enable two-factor authentication

3. Monitoring

   • Check error logs
   • Monitor file changes
   • Track plugin activity