gitea-docker/BACKUP_RUNNER_PLAN.md

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