# Complete Updater System Documentation

## 📋 Overview

A simple and safe updater system for your Laravel CMS. This system allows you to:
- Upload update packages (ZIP files)
- Install updates automatically
- Create backups before updates
- Rollback to previous versions if needed

---

## 🚀 Quick Start

### 1. Access the Updater
Navigate to: `http://your-domain.com/admin/updater`

### 2. Create a Backup (Recommended)
- Click "Create Backup" button
- Enter a reason (optional)
- Wait for backup to complete

### 3. Upload an Update
- Click "Upload Update" button
- Select your ZIP file
- Review update details
- Click "Install" to apply the update

---

## 📦 Update Package Structure

Your update ZIP file must have this structure:

```
update_v1.2.0.zip
├── update.json          # Required: Package information
├── files/              # Optional: Application files to update
│   ├── app/
│   ├── config/
│   ├── Modules/
│   └── resources/
├── migrations/         # Optional: Database migrations
│   └── 2024_01_01_create_table.php
└── scripts/           # Optional: Custom scripts
    ├── pre-update.php
    └── post-update.php
```

### update.json Example:
```json
{
    "version": "1.2.0",
    "title": "Bug Fixes and Improvements",
    "description": "This update fixes several bugs",
    "changelog": "- Fixed login issue\n- Improved performance",
    "author": "Your Company",
    "seeders": ["DatabaseSeeder"]
}
```

---

## 🛠️ Creating Update Packages

### Using Command Line:
```bash
# Basic package
php artisan updater:create-package 1.2.0 --title="Bug Fixes"

# With files
php artisan updater:create-package 1.2.0 --include-files

# With migrations
php artisan updater:create-package 1.2.0 --include-migrations

# Complete package
php artisan updater:create-package 1.2.0 \
    --title="System Update" \
    --description="Major improvements" \
    --include-files \
    --include-migrations \
    --seeders=DatabaseSeeder
```

### Manual Creation:
1. Create a folder for your update
2. Add `update.json` file (required)
3. Add your files in `files/` folder
4. Add migrations in `migrations/` folder (if needed)
5. ZIP everything together

---

## 🔐 Security Features

- ✅ Admin-only access
- ✅ File validation (ZIP format, max 500MB)
- ✅ Automatic backups before updates
- ✅ Version validation
- ✅ Error logging

---

## 📊 Features

### Backup Management
- **Auto Backup**: Created before each update
- **Manual Backup**: Create anytime
- **Download**: Save backups externally
- **Delete**: Clean up old backups

### Update Installation
1. Upload ZIP package
2. System validates the package
3. Creates automatic backup
4. Extracts and applies files
5. Runs migrations (if any)
6. Runs seeders (if specified)
7. Clears caches
8. Marks update as completed

### Rollback
If something goes wrong:
1. Find the update in the list
2. Click "Rollback" button
3. System restores from backup
4. Application returns to previous state

---

## 📝 Database Tables

### updates table:
- `version`: Version number (e.g., 1.2.0)
- `title`: Update title
- `description`: Update description
- `changelog`: What's changed
- `file_path`: Path to ZIP file
- `status`: pending, installing, completed, failed, rolled_back
- `backup_path`: Path to backup file
- `uploaded_by`: User who uploaded
- `installed_at`: Installation timestamp
- `error_message`: Error details (if failed)

---

## 🎯 Routes

```php
GET  /admin/updater              # List all updates
GET  /admin/updater/create       # Upload form
POST /admin/updater              # Upload update
GET  /admin/updater/{id}         # View details
POST /admin/updater/{id}/install # Install update
POST /admin/updater/{id}/rollback # Rollback update
DELETE /admin/updater/{id}       # Delete update

POST /admin/updater/backup/create           # Create backup
GET  /admin/updater/backup/{file}/download  # Download backup
DELETE /admin/updater/backup/{file}         # Delete backup

GET  /admin/updater/status       # System status
```

---

## ⚙️ Configuration

File: `Modules/Updater/config/config.php`

```php
'max_file_size' => 500 * 1024 * 1024,  // 500MB
'backup' => [
    'enabled' => true,
    'auto_create_before_update' => true,
    'max_backup_files' => 10,
],
```

---

## 🐛 Troubleshooting

### Backup Failed
**Error**: "Cannot create backup archive"
**Solution**: 
```bash
# Ensure storage directory is writable
chmod -R 755 storage/
mkdir -p storage/app/backups
chmod -R 755 storage/app/backups
```

### Upload Failed
**Error**: "File too large"
**Solution**: 
- Check PHP upload limits in `php.ini`:
```ini
upload_max_filesize = 500M
post_max_size = 500M
max_execution_time = 300
```

### Installation Failed
**Error**: Various errors
**Solution**:
1. Check error message in update details
2. Review logs: `storage/logs/laravel.log`
3. Use rollback if needed
4. Check file permissions

---

## 📁 Important Files

### Core Files:
- `Modules/Updater/app/Services/UpdaterService.php` - Main logic
- `Modules/Updater/app/Http/Controllers/UpdaterController.php` - Controller
- `Modules/Updater/app/Models/Update.php` - Update model
- `Modules/Updater/routes/web.php` - Routes
- `Modules/Updater/config/config.php` - Configuration

### Views:
- `resources/views/index.blade.php` - Updates list
- `resources/views/create.blade.php` - Upload form
- `resources/views/show.blade.php` - Update details
- `resources/views/status.blade.php` - System status

### Migrations:
- `database/migrations/2025_10_15_000000_create_updates_table.php`

---

## 📈 Version Tracking

The system tracks version in `config/app.php`:
```php
'version' => env('APP_VERSION', '1.0.0'),
```

Add to `.env`:
```
APP_VERSION=1.0.0
```

---

## ✅ Best Practices

### For Developers:
1. Always test on staging first
2. Use semantic versioning (x.y.z)
3. Document changes in changelog
4. Include migrations for database changes
5. Test rollback before deploying

### For Users:
1. **Always backup before updates**
2. Check system requirements
3. Review changelog before installing
4. Monitor application after update
5. Keep backups for 30 days minimum

### For Production:
1. Put site in maintenance mode
2. Create manual backup
3. Apply update during low traffic
4. Test core functionality after update
5. Monitor error logs

---

## 🔄 Update Process Flow

```
1. User uploads ZIP file
   ↓
2. System validates package
   ↓
3. Creates automatic backup
   ↓
4. Extracts package to temp
   ↓
5. Copies files to application
   ↓
6. Runs migrations
   ↓
7. Runs seeders
   ↓
8. Clears caches
   ↓
9. Updates version number
   ↓
10. Marks as completed
```

---

## 📞 Support

### Check Logs:
```bash
tail -f storage/logs/laravel.log
```

### Common Commands:
```bash
# Clear all caches
php artisan cache:clear
php artisan config:clear
php artisan view:clear
php artisan route:clear

# Check permissions
ls -la storage/
ls -la bootstrap/cache/

# Create backup manually
php artisan tinker
>>> app(Modules\Updater\Services\UpdaterService::class)->createBackup('test');
```

### System Requirements:
- PHP 8.1+
- ZipArchive extension
- 256MB+ memory
- Adequate disk space
- Write permissions on storage/

---

## 🎉 Success Indicators

✅ Update shows as "Completed" in list
✅ Version number updated in footer/dashboard
✅ No errors in log files
✅ All features working correctly
✅ Backup file created successfully

---

## ⚠️ Important Notes

1. **Always create backups** before installing updates
2. **Test on staging** environment first
3. **Keep backups** for at least 30 days
4. **Monitor logs** after updates
5. **Don't interrupt** installation process

---

## 📄 License

This updater system is part of your Laravel CMS and follows the same license terms.

---

**Last Updated**: October 2025
**Version**: 1.0.0