diff --git a/readme.md b/readme.md
new file mode 100644
index 0000000..e86a79e
--- /dev/null
+++ b/readme.md
@@ -0,0 +1,155 @@
+# 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