Forgejo/README.md

Forgejo Backup & Restore Scripts

Automated backup and restore scripts for Forgejo Docker installations with safety features and cleanup.

Features

• Automated backups with timestamps
• Consistent snapshots (stops containers during backup)
• Safety-first restore (creates pre-restore backup)
• Automatic cleanup (keeps last 7 backups)
• Flexible restore (latest or specific backup file)

Prerequisites

• Docker and Docker Compose installed
• Forgejo running via docker-compose.yml
• Bash shell environment

Installation

1. Save both scripts in your Forgejo project root directory
2. Make them executable:

chmod +x backup.sh restore.sh

Backup Script

Usage

./backup.sh

What it does

1. Stops Forgejo containers (brief downtime)
2. Creates compressed archive of:
   • forgejo/ directory (data)
   • docker-compose.yml
   • .gitignore
   • README.md
   • .git/ (optional, errors ignored)
3. Restarts Forgejo containers
4. Removes backups older than the last 7

Backup location

Backups are saved to backup/forgejo-backup-YYYY-MM-DD_HH-MM-SS.tar.gz

Automation

Add to crontab for automatic backups:

# Daily backup at 2 AM
0 2 * * * /path/to/forgejo/backup.sh >> /path/to/forgejo/backup/backup.log 2>&1

Restore Script

Usage

# Restore from latest backup
./restore.sh

# Restore from specific backup file
./restore.sh forgejo-backup-2025-01-15_14-30-00.tar.gz

# Restore from full path
./restore.sh /path/to/backup/forgejo-backup-2025-01-15_14-30-00.tar.gz

What it does

1. Prompts for confirmation (destructive operation)
2. Stops Forgejo containers
3. Creates safety backup of current state
4. Moves current data to forgejo.old-TIMESTAMP
5. Extracts selected backup
6. Restarts Forgejo containers

Safety features

• Interactive confirmation required
• Pre-restore backup created automatically
• Current data preserved as forgejo.old-TIMESTAMP
• Config files backed up as *.old-TIMESTAMP

File Structure

forgejo-project/
├── backup.sh           # Backup script
├── restore.sh          # Restore script
├── docker-compose.yml
├── forgejo/            # Forgejo data directory
└── backup/             # Backup storage (auto-created)
    ├── forgejo-backup-2025-11-25_10-00-00.tar.gz
    ├── forgejo-backup-2025-11-24_10-00-00.tar.gz
    └── forgejo-pre-restore-2025-11-25_11-30-00.tar.gz

Important Notes

• Downtime: Brief downtime occurs during backup/restore operations
• Disk space: Backups can be large; monitor available space
• Testing: Test restore procedure before relying on backups
• Permissions: Scripts must be run from Forgejo project root

Recovery Example

If you need to recover from a failed restore:

# Stop containers
docker compose down

# Restore the pre-restore backup
./restore.sh forgejo-pre-restore-YYYY-MM-DD_HH-MM-SS.tar.gz

# Or manually restore old directory
rm -rf forgejo
mv forgejo.old-TIMESTAMP forgejo
docker compose up -d

Troubleshooting

"No backups found"

• Check that backup/ directory exists and contains *.tar.gz files
• Run backup.sh first to create a backup

"Permission denied"

• Ensure scripts are executable: chmod +x backup.sh restore.sh
• Check Docker permissions for your user

"tar: Removing leading / from member names"

• This is normal behavior when using absolute paths
• The warning can be safely ignored

License

MIT License - feel free to modify and use as needed.

Contributing

Improvements welcome! Consider adding:

• Remote backup support (rsync, S3, etc.)
• Encryption for sensitive data
• Email notifications
• Database-only backups for faster operations
• Backup verification tests