# 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