shell/docs/backup-env-safety-guide.md

Backup-Env-Files Safety Guide

Pre-execution Safety Checklist

1. Initial Assessment

# See what files will be backed up
./backup-env-files.sh --list

# Test what would happen without making changes
./backup-env-files.sh --dry-run

2. Backup Your Current State (Optional but Recommended)

# Create a snapshot of your current docker directory
tar -czf ~/docker-backup-$(date +%Y%m%d-%H%M%S).tar.gz ~/docker/

3. Initialize Safely

# First time setup
./backup-env-files.sh --init

4. Regular Backup (Safe)

# Regular backup operation
./backup-env-files.sh

Data Flow Understanding

Backup Operation (Safe - No local changes)

Source: ~/docker/*/.env files
Target: ~/.env-backup/docker-containers/
Remote: Your Gitea repository

Restore Operation (Caution - Modifies local files)

Source: ~/.env-backup/docker-containers/
Target: ~/docker/*/.env files  ⚠️ OVERWRITES LOCAL

File Safety Matrix

Operation	Local Docker Files	Gitea Repository	Local Backup
--list	✅ Read Only	❌ No Contact	❌ No Contact
--dry-run	✅ Read Only	❌ No Contact	❌ No Contact
--init	✅ Read Only	✅ Creates Repo	✅ Creates Structure
Regular backup	✅ Read Only	✅ Updates/Adds Files	✅ Updates Files
--restore	⚠️ OVERWRITES	✅ Read Only	✅ Read Only

Important Notes

What WON'T Happen

• ❌ Your docker repository files won't be touched during backup
• ❌ Files won't be deleted from Gitea repository
• ❌ Your working docker-compose.yml files won't be modified

What WILL Happen

• ✅ .env files will be copied to backup location
• ✅ Changed files will be committed to Gitea
• ✅ Reference docker-compose.yml files may be created (as .ref files)
• ✅ Git history will track all changes

Restore Function Warnings

• ⚠️ --restore WILL overwrite local .env files
• ⚠️ Always prompts for confirmation on conflicts
• ⚠️ Test restore in a safe environment first

Best Practices

1. Always test first: Use --dry-run before your first backup
2. Review file list: Use --list to understand what's being backed up
3. Version control: Your Gitea repo will have full Git history
4. Selective restore: The script asks for confirmation before overwriting existing files
5. Monitor logs: Check logs/env-backup.log for detailed operation history

Emergency Recovery

If something goes wrong:

# Check Git history in backup repository
cd ~/.env-backup
git log --oneline

# Revert to previous state if needed
git reset --hard HEAD~1

# Or restore from your docker directory snapshot
tar -xzf ~/docker-backup-YYYYMMDD-HHMMSS.tar.gz -C ~/