# Backup & Recovery Guide

**Status**: ✅ Complete

**Last Updated**: December 5, 2025

---

## Overview

This guide helps you backup your RiceCoder data and recover from data loss or corruption. Regular backups ensure you don't lose important work.

## Table of Contents

- [What to Backup](#what-to-backup)
- [Backup Methods](#backup-methods)
- [Backup Schedule](#backup-schedule)
- [Recovery Methods](#recovery-methods)
- [Disaster Recovery](#disaster-recovery)
- [Best Practices](#best-practices)

---

## What to Backup

### Critical Data

**Configuration**:
- `~/.ricecoder/config.yaml` - Global configuration
- `.agent/config.yaml` - Project configuration
- `~/.ricecoder/` - All global settings

**Sessions**:
- `~/.ricecoder/sessions/` - Saved chat sessions
- Session history and metadata

**Project Data**:
- `.agent/specs/` - Specifications
- `.agent/hooks/` - Hook configurations
- `.agent/` - All project-specific data

### Optional Data

**Cache**:
- `~/.ricecoder/cache/` - Cached data (can be regenerated)

**Logs**:
- `~/.ricecoder/logs/` - Log files (for debugging)

---

## Backup Methods

### Method 1: Manual Backup (Simple)

**Backup Configuration**:

```bash
# Backup global configuration
cp -r ~/.ricecoder ~/.ricecoder.backup.$(date +%Y%m%d)

# Backup project configuration
cp -r .agent .agent.backup.$(date +%Y%m%d)
```

**Restore Configuration**:

```bash
# Restore global configuration
rm -rf ~/.ricecoder
cp -r ~/.ricecoder.backup.20251205 ~/.ricecoder

# Restore project configuration
rm -rf .agent
cp -r .agent.backup.20251205 .agent
```

### Method 2: Automated Backup Script

**Create backup script** (`backup-ricecoder.sh`):

```bash
#!/bin/bash

# Backup directory
BACKUP_DIR="$HOME/ricecoder-backups"
TIMESTAMP=$(date +%Y%m%d_%H%M%S)
BACKUP_PATH="$BACKUP_DIR/ricecoder_$TIMESTAMP"

# Create backup directory
mkdir -p "$BACKUP_PATH"

# Backup global configuration
cp -r ~/.ricecoder "$BACKUP_PATH/ricecoder_home"

# Backup project configuration (if in a project)
if [ -d ".agent" ]; then
    cp -r .agent "$BACKUP_PATH/agent_project"
fi

# Create tar archive
tar -czf "$BACKUP_PATH.tar.gz" -C "$BACKUP_DIR" "ricecoder_$TIMESTAMP"

# Remove uncompressed backup
rm -rf "$BACKUP_PATH"

# Keep only last 10 backups
ls -t "$BACKUP_DIR"/ricecoder_*.tar.gz | tail -n +11 | xargs rm -f

echo "Backup created: $BACKUP_PATH.tar.gz"
```

**Make script executable**:

```bash
chmod +x backup-ricecoder.sh
```

**Run backup**:

```bash
./backup-ricecoder.sh
```

### Method 3: Cloud Backup

**Using rsync to remote server**:

```bash
# Backup to remote server
rsync -avz ~/.ricecoder user@backup-server:/backups/ricecoder/

# Backup project configuration
rsync -avz .agent user@backup-server:/backups/ricecoder/projects/
```

**Using cloud storage (AWS S3)**:

```bash
# Install AWS CLI
pip install awscli

# Configure AWS credentials
aws configure

# Backup to S3
aws s3 sync ~/.ricecoder s3://my-backup-bucket/ricecoder/

# Backup project configuration
aws s3 sync .agent s3://my-backup-bucket/ricecoder/projects/
```

**Using cloud storage (Google Drive)**:

```bash
# Install rclone
curl https://rclone.org/install.sh | sudo bash

# Configure Google Drive
rclone config

# Backup to Google Drive
rclone sync ~/.ricecoder gdrive:ricecoder-backup/

# Backup project configuration
rclone sync .agent gdrive:ricecoder-backup/projects/
```

### Method 4: Git-Based Backup

**Backup to Git repository**:

```bash
# Create backup repository
mkdir ricecoder-backup
cd ricecoder-backup
git init

# Copy data
cp -r ~/.ricecoder .
cp -r ../.agent .

# Commit and push
git add .
git commit -m "RiceCoder backup $(date)"
git remote add origin https://github.com/YOUR_USERNAME/ricecoder-backup.git
git push -u origin main
```

---

## Backup Schedule

### Recommended Schedule

| Data | Frequency | Retention |
|------|-----------|-----------|
| Configuration | Weekly | 4 weeks |
| Sessions | Daily | 2 weeks |
| Project Data | After changes | 1 month |
| Full Backup | Monthly | 3 months |

### Automated Backup Schedule

**Using cron (macOS/Linux)**:

```bash
# Edit crontab
crontab -e

# Add backup job (daily at 2 AM)
0 2 * * * /path/to/backup-ricecoder.sh

# Add backup job (weekly on Sunday at 3 AM)
0 3 * * 0 /path/to/backup-ricecoder.sh
```

**Using Task Scheduler (Windows)**:

1. Open Task Scheduler
2. Create Basic Task
3. Set trigger (daily, weekly, etc.)
4. Set action to run backup script
5. Enable task

---

## Recovery Methods

### Method 1: Restore from Local Backup

**Restore global configuration**:

```bash
# Stop RiceCoder
pkill rice

# Restore from backup
rm -rf ~/.ricecoder
cp -r ~/.ricecoder.backup ~/.ricecoder

# Restart RiceCoder
rice chat
```

**Restore project configuration**:

```bash
# Restore from backup
rm -rf .agent
cp -r .agent.backup .agent

# Verify restoration
rice config show
```

### Method 2: Restore from Archive

**Extract tar archive**:

```bash
# Extract backup
tar -xzf ricecoder_20251205_120000.tar.gz

# Restore configuration
cp -r ricecoder_20251205_120000/ricecoder_home ~/.ricecoder
cp -r ricecoder_20251205_120000/agent_project .agent
```

### Method 3: Restore from Cloud

**Restore from AWS S3**:

```bash
# Restore from S3
aws s3 sync s3://my-backup-bucket/ricecoder/ ~/.ricecoder

# Restore project configuration
aws s3 sync s3://my-backup-bucket/ricecoder/projects/ .agent
```

**Restore from Google Drive**:

```bash
# Restore from Google Drive
rclone sync gdrive:ricecoder-backup/ ~/.ricecoder

# Restore project configuration
rclone sync gdrive:ricecoder-backup/projects/ .agent
```

### Method 4: Restore from Git

**Clone backup repository**:

```bash
# Clone backup repository
git clone https://github.com/YOUR_USERNAME/ricecoder-backup.git

# Restore configuration
cp -r ricecoder-backup/ricecoder ~/.ricecoder
cp -r ricecoder-backup/agent .agent
```

---

## Disaster Recovery

### Complete Data Loss

If you lose all data:

1. **Reinstall RiceCoder**:
   ```bash
   cargo install ricecoder
   ```

2. **Restore from backup**:
   ```bash
   # Restore configuration
   cp -r ~/.ricecoder.backup ~/.ricecoder
   cp -r .agent.backup .agent
   ```

3. **Verify restoration**:
   ```bash
   rice config show
   rice session list
   ```

### Corrupted Configuration

If configuration is corrupted:

1. **Reset to defaults**:
   ```bash
   rice config reset
   ```

2. **Restore from backup**:
   ```bash
   cp ~/.ricecoder.backup/config.yaml ~/.ricecoder/config.yaml
   ```

3. **Validate configuration**:
   ```bash
   rice config validate
   ```

### Lost Sessions

If sessions are lost:

1. **Check backup**:
   ```bash
   ls -la ~/.ricecoder.backup/sessions/
   ```

2. **Restore sessions**:
   ```bash
   cp -r ~/.ricecoder.backup/sessions/* ~/.ricecoder/sessions/
   ```

3. **Verify sessions**:
   ```bash
   rice session list
   ```

### Partial Data Loss

If only some data is lost:

1. **Identify what's missing**:
   ```bash
   ls -la ~/.ricecoder/
   ls -la .agent/
   ```

2. **Restore missing data**:
   ```bash
   # Restore specific file
   cp ~/.ricecoder.backup/config.yaml ~/.ricecoder/config.yaml
   
   # Restore specific directory
   cp -r ~/.ricecoder.backup/sessions ~/.ricecoder/
   ```

3. **Verify restoration**:
   ```bash
   rice config validate
   rice session list
   ```

---

## Best Practices

### Regular Backups

1. **Backup Frequently**: Backup at least weekly
2. **Automate Backups**: Use cron or Task Scheduler
3. **Test Backups**: Regularly test restoration
4. **Keep Multiple Copies**: Keep backups in multiple locations
5. **Monitor Backups**: Ensure backups complete successfully

### Backup Storage

1. **Local Backup**: Keep a local backup for quick recovery
2. **Remote Backup**: Keep a remote backup for disaster recovery
3. **Cloud Backup**: Use cloud storage for redundancy
4. **Offline Backup**: Keep an offline backup for security
5. **Encrypted Backup**: Encrypt sensitive backups

### Backup Verification

1. **Test Restoration**: Regularly test backup restoration
2. **Verify Integrity**: Verify backup file integrity
3. **Check Completeness**: Ensure all data is backed up
4. **Monitor Size**: Monitor backup size for anomalies
5. **Document Process**: Document your backup process

### Security

1. **Encrypt Backups**: Encrypt sensitive data
2. **Secure Storage**: Store backups securely
3. **Access Control**: Limit access to backups
4. **Audit Logs**: Log backup and restore operations
5. **Secure Deletion**: Securely delete old backups

---

## Backup Checklist

Before relying on backups, ensure you:

- [ ] Identify critical data to backup
- [ ] Choose backup method(s)
- [ ] Create backup script or schedule
- [ ] Test backup process
- [ ] Verify backup completeness
- [ ] Test restoration process
- [ ] Document backup procedure
- [ ] Monitor backup execution
- [ ] Keep backups secure
- [ ] Regularly review and update backups

---

## Troubleshooting

### Issue: Backup Fails

**Problem**: Backup script fails or doesn't complete.

**Solution**:

1. Check disk space: `df -h`
2. Check permissions: `ls -la ~/.ricecoder`
3. Check backup destination: `ls -la ~/ricecoder-backups`
4. Run backup manually: `./backup-ricecoder.sh`
5. Check logs for errors

### Issue: Restoration Fails

**Problem**: Restoration doesn't work or data is corrupted.

**Solution**:

1. Verify backup file: `tar -tzf ricecoder_backup.tar.gz`
2. Check backup integrity: `tar -xzf ricecoder_backup.tar.gz -C /tmp`
3. Verify file permissions: `ls -la ~/.ricecoder`
4. Try restoring to temporary location first
5. Check for conflicts with existing data

### Issue: Backup Size Too Large

**Problem**: Backup files are taking up too much space.

**Solution**:

1. Compress backups: `gzip ricecoder_backup/`
2. Remove old backups: `rm -rf ricecoder_backup_old/`
3. Exclude cache: `--exclude=cache`
4. Use incremental backups
5. Archive old backups to cloud storage

---

## Getting Help

If you need help with backups or recovery:

1. **Check This Guide**: Review this guide for solutions
2. **Check FAQ**: [FAQ](./FAQ.md)
3. **Check Troubleshooting**: [Troubleshooting Guide](./Troubleshooting.md)
4. **Ask Community**: [GitHub Discussions](https://github.com/moabualruz/ricecoder/discussions)
5. **Report Issue**: [GitHub Issues](https://github.com/moabualruz/ricecoder/issues)

---

## See Also

- [Installation & Setup](./Installation-Setup.md) - Installation guide
- [Configuration Guide](./Configuration.md) - Configuration options
- [Upgrade Guide](./Upgrade-Guide.md) - Upgrade instructions
- [Troubleshooting Guide](./Troubleshooting.md) - Troubleshooting help

---

*Last updated: December 5, 2025*