changes

BACKUP_RUNNER_PLAN.md

@@ -0,0 +1,70 @@
+# Gitea Backup Runner Plan
+
+## Objective
+Create a scheduled backup runner that:
+1. Dumps Gitea data using the native `gitea dump` command via `docker exec`
+2. Copies the backup archive from the container to the host
+3. Transfers the backup to remote location `workstation:/mnt/data/git-backups`
+4. Runs automatically once a month via cron
+
+## Current State
+- Existing `gitea-backup.sh` uses `docker run` with tar to backup volume data
+- This new approach uses Gitea's built-in `gitea dump` command which creates a complete backup including database, repos, and settings
+
+## Implementation Plan
+
+### 1. Create Backup Script: `gitea-dump-backup.sh`
+- **Location**: `./gitea-dump-backup.sh`
+- **Functions**:
+  - Generate timestamped backup filename
+  - Execute `gitea dump` inside the container via `docker exec`
+  - Copy the resulting archive from container to host backup directory
+  - Upload to remote workstation via `scp` or `rsync`
+  - Clean up old local backups (keep last N)
+  - Logging and error handling
+
+### 2. Create Cron Configuration
+- **Location**: `./gitea-backup.cron`
+- **Schedule**: First day of each month at 2:00 AM
+  ```
+  0 2 1 * * /path/to/gitea-dump-backup.sh >> /var/log/gitea-backup.log 2>&1
+  ```
+
+### 3. Directory Structure
+```
+gitea-backups/          # Local backup storage (git-ignored)
+├── gitea-dump-20260401-020000.zip
+└── ...
+```
+
+### 4. Remote Transfer Options
+- **Primary**: `rsync` over SSH to `workstation:/mnt/data/git-backups`
+- Requires SSH key-based authentication setup or SSH agent forwarding
+
+### 5. Backup Retention
+- Keep last 3 local backups (configurable)
+- Remote retention handled by remote system
+
+### 6. Prerequisites
+- SSH access to `workstation` server
+- Sufficient disk space in container for dump operation
+- Backup directory created on remote server
+
+## File Changes
+| File | Action |
+|------|--------|
+| `gitea-dump-backup.sh` | Create - main backup script |
+| `gitea-backup.cron` | Create - cron configuration |
+| `.gitignore` | Update - exclude gitea-backups/ directory |
+
+## Security Considerations
+- Store remote credentials securely (SSH key)
+- Ensure backup files have appropriate permissions (600)
+- Log handling for debugging
+
+## Testing Checklist
+- [ ] Run backup script manually
+- [ ] Verify archive contains expected files
+- [ ] Test remote transfer
+- [ ] Verify cron installation
+- [ ] Test error handling scenarios