docs: add README with setup instructions and feature overview

README.md

@@ -1,3 +1,151 @@
-# docker-backup-manager
+# 🐳 Docker Backup Manager
 
-Automated backup and recovery script for Docker-based services with support for compressed archive backups, container lifecycle handling, error logging, and notifications via Gotify and Uptime Kuma.
+This script automates backup and restoration for Docker-based services — stopping containers, archiving important data directories, and restarting containers with optional status reporting and error notifications.
+
+## ✅ What It Does
+
+- Stops one or more Docker containers before backup
+- Archives specified directories into a compressed `.tar.gz` file
+- Stores backups in a local directory
+- Restarts the containers after backup
+- Notifies external systems (like **Uptime Kuma** and **Gotify**) of backup status
+- Cleans up old backups and logs after a set number of days
+
+---
+
+## ⚙️ Features
+
+- **Container Lifecycle Management** before and after backup
+- **Directory Backup** using compressed `.tar.gz` archives
+- **Success/Failure Notifications** via Uptime Kuma and Gotify
+- **Detailed Logging** with timestamped log files
+- **Retention Policy** for automated cleanup of old backups and logs
+
+---
+
+## 📋 Requirements
+
+- **Docker** (with containers already configured)
+- **Bash** (Linux or Unix-based system)
+- **tar** (for directory archiving)
+- *(Optional)* **Uptime Kuma** for monitoring
+- *(Optional)* **Gotify** for alerting
+
+---
+
+## 🚀 Setup
+
+### 1. Clone the Repository
+
+```bash
+git clone https://git.example.com/yourname/docker-backup-manager.git
+cd docker-backup-manager
+````
+
+### 2. Configure Environment Variables
+
+Create a `.env` file:
+
+```env
+# Containers to stop/start during backup (space-separated)
+DOCKER_CONTAINERS="webserver db redis"
+
+# Directories to back up (space-separated)
+DIRECTORIES_TO_BACKUP="/opt/app/config /opt/app/data"
+
+# Backup output location
+BACKUP_DIR=$HOME/docker_backups
+RETENTION_DAYS=7
+BACKUP_TAG=docker-app-backup
+
+# Uptime Kuma (optional)
+UPTIME_KUMA_URL=https://uptime.example.com
+UPTIME_KUMA_API_KEY=your-uptime-api-key
+
+# Gotify (optional)
+GOTIFY_PUSH_URL=https://gotify.example.com
+GOTIFY_PUSH_KEY=your-gotify-token
+```
+
+> Only set the optional variables (`UPTIME_KUMA_*`, `GOTIFY_*`) if you're using those services.
+> Make sure `BACKUP_DIR` exists and is writable.
+
+### 3. Make the Script Executable
+
+```bash
+chmod +x docker_backup.sh
+```
+
+### 4. Run the Backup
+
+```bash
+./docker_backup.sh
+```
+
+### 5. Automate via Cron (Optional)
+
+To schedule daily backups at 3:00 AM:
+
+```bash
+0 3 * * * /path/to/docker_backup.sh
+```
+
+---
+
+## 🔍 How It Works
+
+1. **Stops** specified Docker containers
+2. **Creates** a timestamped archive of key directories
+3. **Restarts** the containers after backup
+4. **Logs** each step with timestamps
+5. **Sends** check-in to Uptime Kuma (if configured)
+6. **Sends** error notifications via Gotify (if enabled)
+7. **Cleans up** files older than `RETENTION_DAYS`
+
+---
+
+## 🖥️ Example Output
+
+```bash
+[$(date)] 🔄 Starting Docker backup job
+[$(date)] 🛑 Stopping Docker containers
+[$(date)] ✅ Stopped container: webserver
+[$(date)] 📦 Backing up directories
+[$(date)] ✅ Backup created at /backups/docker_backup_2025-05-03_03-00-00.tar.gz
+[$(date)] 🚀 Starting Docker containers
+[$(date)] ✅ Started container: webserver
+[$(date)] ✅ Uptime Kuma check-in sent.
+[$(date)] 🧹 Cleaning up files older than 7 days
+[$(date)] ✅ Docker backup job completed
+```
+
+---
+
+## 🧰 Troubleshooting
+
+### Uptime Kuma
+
+* Ensure the URL and API key are set and valid
+* Check that the monitor exists and accepts push updates
+
+### Gotify
+
+* Validate push token and server URL
+* Make sure your Gotify server is accessible
+
+### Docker & Permissions
+
+* Ensure the script has permission to manage Docker (`docker` group or `sudo`)
+* Verify that all listed directories and backup paths are readable/writable
+
+---
+
+## 📄 License
+
+Licensed under the **GNU General Public License v3.0**.
+See the [LICENSE](LICENSE) file for full details.
+
+## 🛠️ About This Script
+
+This script is designed to support sysadmins and DevOps teams who rely on Docker for self-hosted apps and services.
+It's modular, portable, and integrates with your existing monitoring stack.