docs: Add comprehensive deployment guide
📝 Created DEPLOYMENT_GUIDE.md: - Step-by-step server deployment process - Cache clearing procedures (OPcache, WordPress, Browser) - File verification commands - Endpoint testing procedures - Common issues & solutions - Verification checklist - Rollback procedure - Production checklist 🎯 Covers All Common Issues: 1. SPA not loading (dev mode detection) 2. API 500 errors (namespace case) 3. WordPress media not loading (standalone) 4. Changes not reflecting (cache layers) ✅ Ready for Server Deployment!
This commit is contained in:
dwindown
234
DEPLOYMENT_GUIDE.md
Normal file
234
DEPLOYMENT_GUIDE.md
Normal file
@@ -0,0 +1,234 @@
|
|||||||
|
# Deployment Guide
|
||||||
|
|
||||||
|
## Server Deployment Steps
|
||||||
|
|
||||||
|
### 1. Pull Latest Code
|
||||||
|
```bash
|
||||||
|
cd /home/dewepw/woonoow.dewe.pw/wp-content/plugins/woonoow
|
||||||
|
git pull origin main
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Clear All Caches
|
||||||
|
|
||||||
|
#### WordPress Object Cache
|
||||||
|
```bash
|
||||||
|
wp cache flush
|
||||||
|
```
|
||||||
|
|
||||||
|
#### OPcache (PHP)
|
||||||
|
Create a file `clear-opcache.php` in plugin root:
|
||||||
|
```php
|
||||||
|
<?php
|
||||||
|
if (function_exists('opcache_reset')) {
|
||||||
|
opcache_reset();
|
||||||
|
echo "OPcache cleared!";
|
||||||
|
} else {
|
||||||
|
echo "OPcache not available";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then visit: `https://woonoow.dewe.pw/wp-content/plugins/woonoow/clear-opcache.php`
|
||||||
|
|
||||||
|
Or via command line:
|
||||||
|
```bash
|
||||||
|
php -r "opcache_reset();"
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Browser Cache
|
||||||
|
- Hard refresh: `Ctrl+Shift+R` (Windows/Linux) or `Cmd+Shift+R` (Mac)
|
||||||
|
- Or clear browser cache completely
|
||||||
|
|
||||||
|
### 3. Verify Files
|
||||||
|
```bash
|
||||||
|
# Check if Routes.php has correct namespace
|
||||||
|
grep "use WooNooW" includes/Api/Routes.php
|
||||||
|
|
||||||
|
# Should show:
|
||||||
|
# use WooNooW\Api\PaymentsController;
|
||||||
|
# use WooNooW\Api\StoreController;
|
||||||
|
# use WooNooW\Api\DeveloperController;
|
||||||
|
# use WooNooW\Api\SystemController;
|
||||||
|
|
||||||
|
# Check if Assets.php has correct is_dev_mode()
|
||||||
|
grep -A 5 "is_dev_mode" includes/Admin/Assets.php
|
||||||
|
|
||||||
|
# Should show:
|
||||||
|
# defined('WOONOOW_ADMIN_DEV') && WOONOOW_ADMIN_DEV === true
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Check File Permissions
|
||||||
|
```bash
|
||||||
|
# Plugin files should be readable
|
||||||
|
find . -type f -exec chmod 644 {} \;
|
||||||
|
find . -type d -exec chmod 755 {} \;
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Test Endpoints
|
||||||
|
|
||||||
|
#### Test API
|
||||||
|
```bash
|
||||||
|
curl -I https://woonoow.dewe.pw/wp-json/woonoow/v1/store/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
Should return `200 OK`, not `500 Internal Server Error`.
|
||||||
|
|
||||||
|
#### Test Admin SPA
|
||||||
|
Visit: `https://woonoow.dewe.pw/wp-admin/admin.php?page=woonoow`
|
||||||
|
|
||||||
|
Should load the SPA, not show blank page or errors.
|
||||||
|
|
||||||
|
#### Test Standalone
|
||||||
|
Visit: `https://woonoow.dewe.pw/admin`
|
||||||
|
|
||||||
|
Should load standalone admin interface.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Common Issues & Solutions
|
||||||
|
|
||||||
|
### Issue 1: SPA Not Loading (Blank Page)
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Blank page in wp-admin
|
||||||
|
- Console errors about `@react-refresh` or `localhost:5173`
|
||||||
|
|
||||||
|
**Cause:**
|
||||||
|
- Server is in dev mode
|
||||||
|
- Trying to load from Vite dev server
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# Check wp-config.php - remove or set to false:
|
||||||
|
define('WOONOOW_ADMIN_DEV', false);
|
||||||
|
|
||||||
|
# Or remove the line completely
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue 2: API 500 Errors
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- All API endpoints return 500
|
||||||
|
- Error: `Class "WooNooWAPIPaymentsController" not found`
|
||||||
|
|
||||||
|
**Cause:**
|
||||||
|
- Namespace case mismatch
|
||||||
|
- Old code cached
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# 1. Pull latest code
|
||||||
|
git pull origin main
|
||||||
|
|
||||||
|
# 2. Clear OPcache
|
||||||
|
php -r "opcache_reset();"
|
||||||
|
|
||||||
|
# 3. Clear WordPress cache
|
||||||
|
wp cache flush
|
||||||
|
|
||||||
|
# 4. Verify namespace fix
|
||||||
|
grep "use WooNooW\\\\Api" includes/Api/Routes.php
|
||||||
|
```
|
||||||
|
|
||||||
|
### Issue 3: WordPress Media Not Loading (Standalone)
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- "WordPress Media library is not loaded" error
|
||||||
|
- Image upload doesn't work
|
||||||
|
|
||||||
|
**Cause:**
|
||||||
|
- Missing wp.media scripts
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
- Already fixed in latest code
|
||||||
|
- Pull latest: `git pull origin main`
|
||||||
|
- Clear cache
|
||||||
|
|
||||||
|
### Issue 4: Changes Not Reflecting
|
||||||
|
|
||||||
|
**Symptoms:**
|
||||||
|
- Code changes don't appear
|
||||||
|
- Still seeing old errors
|
||||||
|
|
||||||
|
**Cause:**
|
||||||
|
- Multiple cache layers
|
||||||
|
|
||||||
|
**Solution:**
|
||||||
|
```bash
|
||||||
|
# 1. Clear PHP OPcache
|
||||||
|
php -r "opcache_reset();"
|
||||||
|
|
||||||
|
# 2. Clear WordPress object cache
|
||||||
|
wp cache flush
|
||||||
|
|
||||||
|
# 3. Clear browser cache
|
||||||
|
# Hard refresh: Ctrl+Shift+R
|
||||||
|
|
||||||
|
# 4. Restart PHP-FPM (if needed)
|
||||||
|
sudo systemctl restart php8.1-fpm
|
||||||
|
# or
|
||||||
|
sudo systemctl restart php-fpm
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification Checklist
|
||||||
|
|
||||||
|
After deployment, verify:
|
||||||
|
|
||||||
|
- [ ] Git pull completed successfully
|
||||||
|
- [ ] OPcache cleared
|
||||||
|
- [ ] WordPress cache cleared
|
||||||
|
- [ ] Browser cache cleared
|
||||||
|
- [ ] API endpoints return 200 OK
|
||||||
|
- [ ] WP-Admin SPA loads correctly
|
||||||
|
- [ ] Standalone admin loads correctly
|
||||||
|
- [ ] No console errors
|
||||||
|
- [ ] Dashboard displays data
|
||||||
|
- [ ] Settings pages work
|
||||||
|
- [ ] Image upload works
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Rollback Procedure
|
||||||
|
|
||||||
|
If deployment causes issues:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# 1. Check recent commits
|
||||||
|
git log --oneline -5
|
||||||
|
|
||||||
|
# 2. Rollback to previous commit
|
||||||
|
git reset --hard <commit-hash>
|
||||||
|
|
||||||
|
# 3. Clear caches
|
||||||
|
php -r "opcache_reset();"
|
||||||
|
wp cache flush
|
||||||
|
|
||||||
|
# 4. Verify
|
||||||
|
curl -I https://woonoow.dewe.pw/wp-json/woonoow/v1/store/settings
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Production Checklist
|
||||||
|
|
||||||
|
Before going live:
|
||||||
|
|
||||||
|
- [ ] All features tested
|
||||||
|
- [ ] No console errors
|
||||||
|
- [ ] No PHP errors in logs
|
||||||
|
- [ ] Performance tested
|
||||||
|
- [ ] Security reviewed
|
||||||
|
- [ ] Backup created
|
||||||
|
- [ ] Rollback plan ready
|
||||||
|
- [ ] Monitoring in place
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Support
|
||||||
|
|
||||||
|
If issues persist:
|
||||||
|
1. Check error logs: `/home/dewepw/woonoow.dewe.pw/wp-content/debug.log`
|
||||||
|
2. Check PHP error logs: `/var/log/php-fpm/error.log`
|
||||||
|
3. Enable WP_DEBUG temporarily to see detailed errors
|
||||||
|
4. Contact development team with error details
|
||||||
Reference in New Issue
Block a user