Skip to content

Backup Recovery Guide

Jump to bottom
Mo Abualruz edited this page Dec 5, 2025 · 1 revision

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

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:

# 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:

# 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):

#!/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:

chmod +x backup-ricecoder.sh

Run backup:

./backup-ricecoder.sh

Method 3: Cloud Backup

Using rsync to remote server:

# 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):

# 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):

# 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:

# 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):

# 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:

# Stop RiceCoder
pkill rice

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

# Restart RiceCoder
rice chat

Restore project configuration:

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

# Verify restoration
rice config show

Method 2: Restore from Archive

Extract tar archive:

# 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:

# 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:

# 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:

# 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:

    cargo install ricecoder

  2. Restore from backup:

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

  3. Verify restoration:

    rice config show
rice session list

Corrupted Configuration

If configuration is corrupted:

  1. Reset to defaults:

    rice config reset

  2. Restore from backup:

    cp ~/.ricecoder.backup/config.yaml ~/.ricecoder/config.yaml

  3. Validate configuration:

    rice config validate

Lost Sessions

If sessions are lost:

  1. Check backup:

    ls -la ~/.ricecoder.backup/sessions/

  2. Restore sessions:

    cp -r ~/.ricecoder.backup/sessions/* ~/.ricecoder/sessions/

  3. Verify sessions:

    rice session list

Partial Data Loss

If only some data is lost:

  1. Identify what's missing:

    ls -la ~/.ricecoder/
ls -la .agent/

  2. Restore missing data:

    # Restore specific file
cp ~/.ricecoder.backup/config.yaml ~/.ricecoder/config.yaml

# Restore specific directory
cp -r ~/.ricecoder.backup/sessions ~/.ricecoder/

  3. Verify restoration:

    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
  3. Check Troubleshooting: Troubleshooting Guide
  4. Ask Community: GitHub Discussions
  5. Report Issue: GitHub Issues

See Also

Last updated: December 5, 2025

Clone this wiki locally