From 9d0918108579cc6c0a55d5f9aaa8fdc0bc3b4b3e Mon Sep 17 00:00:00 2001
From: Peter Wood <peter@peterwood.dev>
Date: Thu, 29 May 2025 14:24:38 -0400
Subject: [PATCH] feat: Add Backup-Env-Files Safety Guide documentation

---
 docs/backup-env-safety-guide.md | 106 ++++++++++++++++++++++++++++++++
 1 file changed, 106 insertions(+)
 create mode 100644 docs/backup-env-safety-guide.md

diff --git a/docs/backup-env-safety-guide.md b/docs/backup-env-safety-guide.md
new file mode 100644
index 0000000..938b577
--- /dev/null
+++ b/docs/backup-env-safety-guide.md
@@ -0,0 +1,106 @@
+# Backup-Env-Files Safety Guide
+
+## Pre-execution Safety Checklist
+
+### 1. Initial Assessment
+
+```bash
+# 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)
+
+```bash
+# 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
+
+```bash
+# First time setup
+./backup-env-files.sh --init
+```
+
+### 4. Regular Backup (Safe)
+
+```bash
+# 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:
+
+```bash
+# 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 ~/
+```