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:

```bash
chmod +x backup.sh restore.sh
```

## Backup Script

### Usage

```bash
./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:

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

## Restore Script

### Usage

```bash
# 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:

```bash
# 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