# CompareKit - Backup & Version Control Guide

Complete guide for managing backups, versioning, and rollbacks.

---

## 📋 Table of Contents

1. [Local Backups](#local-backups)
2. [Server Backups (cPanel)](#server-backups-cpanel)
3. [Git Version Control](#git-version-control)
4. [Version Numbering](#version-numbering)
5. [Rollback Procedures](#rollback-procedures)
6. [Best Practices](#best-practices)

---

## 🖥️ Local Backups

### Quick Backup

```bash
npm run backup
```

Or directly:
```bash
bash backup.sh
```

### What Gets Backed Up

✅ **Included:**
- All source code (`src/`)
- Frontend files (`public/`)
- Configuration files (`package.json`, `.env.example`)
- Documentation
- Scripts

❌ **Excluded:**
- `node_modules/` (can be reinstalled)
- `cache/` (regenerated)
- `generated/` (temporary)
- `.git/` (separate version control)

### Backup Location

Backups are stored in: `../CompareKit-Backups/`

**Format:** `CompareKit-backup-YYYYMMDD-HHMMSS.tar.gz`

**Example:** `CompareKit-backup-20251115-221850.tar.gz`

### Automatic Cleanup

The backup script automatically keeps the **last 10 backups** and deletes older ones.

---

## 🔄 Restore from Local Backup

### Interactive Restore

```bash
npm run restore
```

Or directly:
```bash
bash restore.sh
```

### Manual Restore

1. **List available backups:**
   ```bash
   ls -lht ../CompareKit-Backups/
   ```

2. **Extract specific backup:**
   ```bash
   cd /Users/rogzim/Projects/CompareKit
   tar -xzf ../CompareKit-Backups/CompareKit-backup-20251115-221850.tar.gz
   ```

3. **Reinstall dependencies:**
   ```bash
   npm install
   ```

4. **Check .env file:**
   Make sure your `.env` file has the correct settings.

---

## 🌐 Server Backups (cPanel)

### Method 1: cPanel Backup Tool

**Full Account Backup:**

1. Login to cPanel
2. Go to **"Backup"** or **"Backup Wizard"**
3. Click **"Download a Full Account Backup"**
4. Select **"Home Directory"**
5. Enter your email for notification
6. Click **"Generate Backup"**
7. Download when ready

**Download Location:** Usually sent to your email or available in cPanel File Manager

---

### Method 2: Manual File Backup via cPanel

**Quick Backup:**

1. Go to **File Manager**
2. Navigate to `public_html/CompareKit/`
3. Select the folder
4. Click **"Compress"**
5. Choose **"Tar GZip Archive"**
6. Name it: `comparekit-backup-YYYY-MM-DD.tar.gz`
7. Click **"Download"**

**Storage:** Save to your local computer or cloud storage

---

### Method 3: SSH Backup (If Available)

If you have SSH access:

```bash
# Login via SSH
ssh username@your-server.com

# Navigate to project
cd /home/ziro2006/public_html/CompareKit

# Create backup
tar -czf ~/comparekit-backup-$(date +%Y%m%d).tar.gz \
  --exclude='node_modules' \
  --exclude='cache/*' \
  --exclude='generated/*' \
  .

# Download to local (from your local terminal)
scp username@your-server.com:~/comparekit-backup-YYYYMMDD.tar.gz ~/Downloads/
```

---

### Server Restore Procedure

**Via cPanel File Manager:**

1. **Backup current version first!**
   - Compress current `CompareKit` folder
   - Download it

2. **Stop the Node.js app:**
   - cPanel → Setup Node.js App → STOP APP

3. **Delete old files:**
   - Delete everything in `/public_html/CompareKit/`
   - **EXCEPT** `.env` (back it up first!)

4. **Upload backup:**
   - Upload your backup `.tar.gz` file
   - Extract it in `/public_html/CompareKit/`

5. **Restore .env:**
   - Make sure `.env` is in place with correct values

6. **Restart app:**
   - cPanel → Setup Node.js App
   - Click **"Run NPM Install"** (if needed)
   - Click **"RESTART"**

---

## 🎯 Git Version Control

### Current Status

✅ Git initialized
✅ Initial commit created (v1.0.0)
✅ Proper `.gitignore` configured

### Common Git Commands

**Check status:**
```bash
git status
```

**View commit history:**
```bash
git log --oneline
```

**Create a new commit:**
```bash
git add .
git commit -m "Description of changes"
```

**View changes:**
```bash
git diff
```

**Revert to previous commit:**
```bash
git log --oneline          # Find the commit hash
git checkout <commit-hash> # Go back to that version
```

**Create a tag for version:**
```bash
git tag v1.0.1
git tag -l                 # List all tags
```

---

## 🔢 Version Numbering

### Semantic Versioning

Format: **MAJOR.MINOR.PATCH** (e.g., 1.0.0)

- **MAJOR** (1.x.x): Breaking changes, incompatible API changes
- **MINOR** (x.1.x): New features, backwards compatible
- **PATCH** (x.x.1): Bug fixes, minor improvements

### Current Version

**v1.0.0** - Initial production release

### Bump Version

**Patch (1.0.0 → 1.0.1)** - Bug fixes:
```bash
npm run version:patch
```

**Minor (1.0.0 → 1.1.0)** - New features:
```bash
npm run version:minor
```

**Major (1.0.0 → 2.0.0)** - Breaking changes:
```bash
npm run version:major
```

This will:
1. Update `package.json`
2. Update `VERSION` file
3. Create a Git commit
4. Create a Git tag

### Update CHANGELOG

After version bump, update `CHANGELOG.md`:

```markdown
## [1.0.1] - 2025-11-16

### Fixed
- Bug fix description

### Added
- New feature description
```

---

## ⏮️ Rollback Procedures

### Scenario 1: Just Updated, Need to Rollback

**Local:**
```bash
npm run restore
# Select the backup before your changes
```

**Server:**
1. Stop Node.js app
2. Restore from latest backup (see Server Restore above)
3. Restart app

---

### Scenario 2: Rollback to Specific Version (Git)

**View versions:**
```bash
git log --oneline
git tag -l
```

**Rollback to specific version:**
```bash
# Rollback to v1.0.0
git checkout v1.0.0

# OR rollback to specific commit
git checkout <commit-hash>

# Create a new branch from there if needed
git checkout -b rollback-v1.0.0
```

**Make it permanent:**
```bash
git revert HEAD~3  # Revert last 3 commits
# OR
git reset --hard <commit-hash>  # ⚠️ DESTRUCTIVE!
```

---

### Scenario 3: Server Crashed, Emergency Restore

**Quick Recovery:**

1. **Download latest backup from:**
   - cPanel Backups
   - Your local backup folder
   - Cloud storage (if you stored there)

2. **Via cPanel:**
   - File Manager → Upload backup
   - Extract to `CompareKit/`
   - Restore `.env` file
   - Node.js App → RESTART

3. **Test:**
   - Visit `https://kodepilot.com/CompareKit/health`
   - Generate a test image

---

## 📅 Best Practices

### Daily Workflow

1. **Before making changes:**
   ```bash
   npm run backup
   git status
   ```

2. **After testing changes:**
   ```bash
   git add .
   git commit -m "Descriptive message"
   ```

3. **Before deploying to server:**
   ```bash
   npm run backup              # Create local backup
   bash prepare-upload.sh      # Prepare files
   # Then upload to server
   ```

4. **After successful deployment:**
   - Backup server via cPanel
   - Tag version in Git if it's a release

---

### Backup Schedule

**Local Development:**
- ✅ Before major changes
- ✅ Before version updates
- ✅ After completing features

**Server (Production):**
- ✅ Before deploying updates
- ✅ Weekly automated backups (via cPanel)
- ✅ After major changes
- ✅ Before npm install/updates

---

### Version Release Workflow

1. **Make changes and test locally**

2. **Update version:**
   ```bash
   npm run version:minor  # or patch/major
   ```

3. **Update CHANGELOG.md:**
   - Document all changes

4. **Commit and tag:**
   ```bash
   git add CHANGELOG.md
   git commit -m "Update changelog for vX.X.X"
   git tag vX.X.X
   ```

5. **Create backup:**
   ```bash
   npm run backup
   ```

6. **Deploy to server:**
   ```bash
   bash prepare-upload.sh
   # Upload files
   # Restart app
   ```

7. **Test production:**
   - Visit site
   - Test all features
   - Check health endpoint

---

## 🆘 Emergency Contacts

**If something goes wrong:**

1. **Check logs:**
   - cPanel → Errors (look for Passenger logs)
   - Browser console (F12)

2. **Rollback immediately:**
   - Use most recent backup
   - Restore via cPanel

3. **Test on local first:**
   - Never deploy untested changes
   - Always keep `.env` backed up

---

## 📊 Quick Reference

| Task | Command |
|------|---------|
| Create backup | `npm run backup` |
| Restore backup | `npm run restore` |
| Check Git status | `git status` |
| Commit changes | `git add . && git commit -m "message"` |
| Bump patch version | `npm run version:patch` |
| Bump minor version | `npm run version:minor` |
| View backups | `ls -lht ../CompareKit-Backups/` |
| View Git history | `git log --oneline` |

---

## ✅ Checklist Before Updates

- [ ] Current code is backed up (local)
- [ ] Current server is backed up (cPanel)
- [ ] Changes tested locally
- [ ] `.env` file backed up
- [ ] Version number updated
- [ ] CHANGELOG.md updated
- [ ] Git commit created
- [ ] Prepared upload package
- [ ] Ready to rollback if needed

---

**Stay safe! Always backup before making changes!** 🛡️
