# Product Updates Production Deployment Guide


**Last Updated:** 2026-03-25

## Overview

This guide provides step-by-step instructions for deploying and maintaining the Product Updates storage system in production. It covers pre-deployment checks, post-deployment verification, monitoring setup, troubleshooting, and rollback procedures.

## Pre-Deployment Checklist

### 1. Server Requirements

- [ ] PHP 7.4+ with required extensions (json, mbstring, gd)
- [ ] Web server (Apache/Nginx) configured
- [ ] Write permissions on `v2/data/` directory
- [ ] Write permissions on `v2/data/images/` directory (or fallback locations)
- [ ] PHP user has ownership of data directories

### 2. File Permissions

Run the initialization script to set up correct permissions:

```bash
# Access via browser (requires admin login):
# /v2/admin/produkt-updates/init-storage.php

# Or manually:
sudo mkdir -p /var/www/html/v2/data/images/produkt-updates/
sudo chown -R www-data:www-data /var/www/html/v2/data/
sudo chmod -R 755 /var/www/html/v2/data/
sudo chmod 644 /var/www/html/v2/data/produkt_updates.json
```

### 3. Configuration

- [ ] Update `v2/config/storage-diagnostics-auth.php`:

  - Set `STORAGE_DIAGNOSTICS_AUTH_METHOD` to `'ip_whitelist'` or `'token'`
  - Add production IP addresses to whitelist
  - Set strong token if using token authentication

- [ ] Verify `.gitignore` includes:
  - `v2/data/images/`
  - `v2/data/backups/`
  - `v2/data/rate-limit-storage.json`
  - `v2/data/storage-metrics.json`
  - `v2/logs/`

### 4. Backup Existing Data

If migrating from old system:

```bash
# Backup existing data file
cp /var/www/html/v2/data/produkt_updates.json /var/www/html/v2/data/backups/produkt_updates_backup_$(date +%Y%m%d_%H%M%S).json

# Backup existing images
tar -czf /var/www/html/v2/data/backups/images_backup_$(date +%Y%m%d_%H%M%S).tar.gz /var/www/html/v2/img/produkt-updates/
```

## Deployment Steps

### Step 1: Deploy Code

Deploy all files via your standard deployment process (Git, rsync, etc.).

**Image public URLs:** After pulling `.htaccess` changes, canonical browser/feed paths are `/produkt-updates/bilder/{file}` (PHP: `v2/pages/produkt-updates-bilder.php`). Rewrite `produkt_updates.json` image fields from legacy `/wp-content/uploads/produkt-updates/…` or `/produkt-updates/media/…` if needed:

`php v2/admin/produkt-updates/normalize-produkt-updates-image-paths.php --dry-run` then `--write`.

Verify a known asset returns **200** at `/produkt-updates/bilder/{filename}`; that `/wp-content/uploads/produkt-updates/{filename}` and `/produkt-updates/media/{filename}` **301** to `/produkt-updates/bilder/{filename}`.

### Step 2: Initialize Storage

1. Access admin panel: `/v2/pages/produkt_updates_admin.php`
2. Log in with admin credentials
3. Navigate to Settings > Storage Status
4. Click "Initialize Storage" or access: `/v2/admin/produkt-updates/init-storage.php`
5. Verify all directories are created and writable

### Step 3: Migrate Existing Data (if needed)

If data exists in `/tmp/` or old locations:

1. **Check Migration Status:**

   - Data: `/v2/admin/produkt-updates/migrate-to-persistent-storage.php?action=check`
   - Images: `/v2/admin/produkt-updates/migrate-images-to-persistent.php?action=check`

2. **Perform Migration:**

   - Data: `/v2/admin/produkt-updates/migrate-to-persistent-storage.php?action=migrate` (POST with CSRF token)
   - Images: `/v2/admin/produkt-updates/migrate-images-to-persistent.php?action=migrate&cleanup=0` (POST with CSRF token)

3. **Verify Migration:**
   - Run: `/v2/admin/produkt-updates/verify-migration.php`
   - Check admin panel shows data
   - Test image uploads and display

### Step 4: Verify Endpoints

Test all diagnostic endpoints (requires authentication):

- `/v2/api/produkt-updates-storage-health.php` - Quick health check
- `/v2/api/produkt-updates-server-investigation.php` - Full diagnostics
- `/v2/api/produkt-updates-data-location-check.php` - Data location comparison
- `/v2/api/produkt-updates-image-investigation.php` - Image storage investigation

## Post-Deployment Verification

### 1. Functional Tests

- [ ] Admin panel loads and shows data
- [ ] Can create/edit/delete features
- [ ] Can upload images
- [ ] Images display correctly on public pages
- [ ] Public pages show correct content
- [ ] RSS feed works
- [ ] Sitemap generates correctly

### 2. Storage Verification

- [ ] Data file resolves to **`wp-content/uploads/produkt-updates/produkt_updates.json`** on production (repo `v2/data/produkt_updates.json` is fallback only)
- [ ] Images are on disk under **`wp-content/uploads/produkt-updates/`**; public URLs in JSON use **`/produkt-updates/bilder/`**
- [ ] No files in `/tmp/` locations
- [ ] File permissions are correct (755 for dirs, 644 for files)
- [ ] Storage Status in admin panel shows "OK"

### 3. Performance Check

- [ ] Page load times acceptable
- [ ] Image serving works efficiently
- [ ] No errors in PHP error log
- [ ] No errors in storage log (`v2/logs/produkt-updates-storage.log`)

## Monitoring Setup

### 1. Health Check Endpoint

Set up monitoring to check `/v2/api/produkt-updates-storage-health.php`:

- **Frequency:** Every 5 minutes
- **Alert on:** `overall_status` !== 'OK'
- **Alert on:** `using_volatile_storage` === true
- **Alert on:** `critical_issues_count` > 0

### 2. Log Monitoring

Monitor `v2/logs/produkt-updates-storage.log` for:

- CRITICAL level messages
- ERROR level messages
- WARNING messages about volatile storage
- High error rates

### 3. Metrics Tracking

Monitor `v2/data/storage-metrics.json`:

- `error_rate` > 5%
- `last_successful_write` older than 24 hours
- Rapid increase in `error_count`

### 4. Automated Alerts

Set up email alerts for:

- Volatile storage detected
- Migration failures
- High error rates (>5%)
- No writes in 24+ hours
- Disk space low

## Troubleshooting

### Issue: Admin Panel Shows No Data

**Symptoms:**

- Admin panel is empty
- Public pages may show old data or be empty

**Diagnosis:**

1. Check `/v2/api/produkt-updates-data-location-check.php`
2. Verify data file location
3. Check if using volatile storage

**Solution:**

1. Run migration script if data is in `/tmp/`
2. Fix file permissions on `v2/data/`
3. Verify data file exists and is readable

### Issue: Images Not Displaying

**Symptoms:**

- Images show broken links
- 404 errors for images

**Diagnosis:**

1. Check `/v2/api/produkt-updates-image-investigation.php`
2. Verify image storage location
3. Check image proxy endpoint logs

**Solution:**

1. Run image migration if images are in `/tmp/`
2. Fix file permissions on image directory
3. Verify images exist in persistent location
4. Check JSON references are correct

### Issue: Permission Denied Errors

**Symptoms:**

- Cannot save data
- Cannot upload images
- Permission errors in logs

**Solution:**

```bash
# Fix ownership
sudo chown -R www-data:www-data /var/www/html/v2/data/

# Fix permissions
sudo chmod -R 755 /var/www/html/v2/data/
sudo chmod 644 /var/www/html/v2/data/produkt_updates.json

# Restart web server
sudo service apache2 restart  # or nginx restart
```

### Issue: Data Loss After Server Restart

**Symptoms:**

- Data disappears after restart
- Images missing after restart

**Diagnosis:**

- Check if using volatile `/tmp/` storage
- Run `/v2/api/produkt-updates-storage-health.php`

**Solution:**

1. Immediately run migration scripts
2. Fix permissions on persistent directories
3. Verify migration completed successfully
4. Set up monitoring to prevent future issues

## Rollback Procedures

### Rollback Data Migration

If data migration causes issues:

1. Access rollback endpoint:
   `/v2/admin/produkt-updates/migrate-to-persistent-storage.php?action=rollback`

2. Or manually restore from backup:
   ```bash
   cp /var/www/html/v2/data/backups/produkt_updates_YYYY-MM-DD_HHMMSS.json /var/www/html/v2/data/produkt_updates.json
   ```

### Rollback Code Changes

If code changes cause issues:

1. Revert to previous Git commit
2. Restore from backup if data was modified
3. Verify system functionality
4. Review logs for errors

## Maintenance Tasks

### Daily

- [ ] Check storage health endpoint
- [ ] Review error logs
- [ ] Verify no volatile storage warnings

### Weekly

- [ ] Review storage metrics
- [ ] Check disk space
- [ ] Verify backup files exist
- [ ] Test admin panel functionality

### Monthly

- [ ] Review and clean old backups (keep 30 days)
- [ ] Review and rotate logs
- [ ] Verify file permissions
- [ ] Test migration scripts
- [ ] Review security audit

## Best Practices

1. **Always use persistent storage** - Never rely on `/tmp/` for production
2. **Regular backups** - Automated backups of data file and images
3. **Monitor health** - Set up automated health checks
4. **Test migrations** - Test migration scripts in staging first
5. **Document changes** - Keep track of configuration changes
6. **Review logs** - Regularly review storage logs for issues
7. **Update documentation** - Keep deployment guide current

## Emergency Contacts

- **Primary Contact:** Hady Elhady (hady@ordio.com)
- **Error Alerts:** All error emails go to hady@ordio.com

## Additional Resources

- Storage Migration Guide: `docs/PRODUCT_UPDATES_STORAGE_MIGRATION.md`
- Cursor Rules: `.cursor/rules/product-updates.mdc`
- Admin User Guide: `v2/admin/produkt-updates/USER_GUIDE.md`
- Code Documentation: `v2/admin/produkt-updates/CODE_DOCUMENTATION.md`