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.

docker_backup.sh

@@ -0,0 +1,117 @@
+#!/bin/bash
+
+# === Load configuration from .env ===
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+if [[ -f "$SCRIPT_DIR/.env" ]]; then
+    source "$SCRIPT_DIR/.env"
+else
+    echo "[$(date)] ❌ Missing .env file in $SCRIPT_DIR"
+    exit 1
+fi
+
+# Ensure backup directory exists
+mkdir -p "$BACKUP_DIR"
+
+# === Timestamp & File Setup ===
+TIMESTAMP=$(date +"%Y-%m-%d_%H-%M-%S")
+OUTPUT_FILE="$BACKUP_DIR/docker_backup_$TIMESTAMP.tar.gz"
+LOG_FILE="$BACKUP_DIR/docker_backup_$TIMESTAMP.log"
+
+# === Logging helper ===
+log() {
+    echo "[$(date)] $1" | tee -a "$LOG_FILE"
+}
+
+# === Uptime Kuma Check-in ===
+uptime_kuma_checkin() {
+    if [[ -n "$UPTIME_KUMA_URL" && -n "$UPTIME_KUMA_API_KEY" ]]; then
+        curl -s "${UPTIME_KUMA_URL}/api/push/${UPTIME_KUMA_API_KEY}?status=up&msg=OK" > /dev/null
+        log "✅ Uptime Kuma check-in sent."
+    fi
+}
+
+# === Gotify Error Notification ===
+gotify_error_notify() {
+    local summary="Docker backup errors on $(hostname):\n$1"
+    if [[ -n "$GOTIFY_PUSH_URL" && -n "$GOTIFY_PUSH_KEY" ]]; then
+        curl -s -X POST "${GOTIFY_PUSH_URL}/message?token=${GOTIFY_PUSH_KEY}" \
+            -F "title=[${BACKUP_TAG}] Docker Backup Error on $(hostname)" \
+            -F "message=$(echo -e "$summary" | head -c 1000)" \
+            -F "priority=5" > /dev/null
+        log "⚠️ Gotify error notification sent."
+    fi
+}
+
+# === Stop Containers ===
+stop_containers() {
+    log "🛑 Stopping Docker containers"
+    for container in ${DOCKER_CONTAINERS[@]}; do
+        docker stop "$container" >> "$LOG_FILE" 2>&1
+        if [[ $? -eq 0 ]]; then
+            log "✅ Stopped container: $container"
+        else
+            log "❌ Failed to stop container: $container"
+        fi
+    done
+}
+
+# === Start Containers ===
+start_containers() {
+    log "🚀 Starting Docker containers"
+    for container in ${DOCKER_CONTAINERS[@]}; do
+        docker start "$container" >> "$LOG_FILE" 2>&1
+        if [[ $? -eq 0 ]]; then
+            log "✅ Started container: $container"
+        else
+            log "❌ Failed to start container: $container"
+        fi
+    done
+}
+
+# === Backup Directories ===
+backup_directories() {
+    log "📦 Backing up directories"
+    tar -czf "$OUTPUT_FILE" ${DIRECTORIES_TO_BACKUP[@]} >> "$LOG_FILE" 2>&1
+    if [[ $? -eq 0 ]]; then
+        log "✅ Backup created at $OUTPUT_FILE"
+    else
+        log "❌ Failed to create backup archive"
+        gotify_error_notify "Backup failed while archiving directories."
+        exit 1
+    fi
+}
+
+# === Cleanup Old Backups and Logs ===
+cleanup_old_files() {
+    log "🧹 Cleaning up files older than $RETENTION_DAYS days"
+    find "$BACKUP_DIR" \( -name "docker_backup_*.tar.gz" -o -name "docker_backup_*.log" \) -type f -mtime +$RETENTION_DAYS -exec rm -f {} \;
+}
+
+# === Error Scanning ===
+scan_logs_for_errors() {
+    log "🔍 Scanning logs for errors"
+    ERRORS=""
+    while IFS= read -r logfile; do
+        LOG_ERRORS=$(grep -Ei "error|failed|❌" "$logfile")
+        if [[ -n "$LOG_ERRORS" ]]; then
+            ERRORS+="\n$(basename "$logfile"):\n$LOG_ERRORS\n"
+        fi
+    done < <(find "$BACKUP_DIR" -name "docker_backup_*.log" -type f -mtime -$RETENTION_DAYS)
+
+    if [[ -n "$ERRORS" ]]; then
+        gotify_error_notify "$ERRORS"
+    fi
+}
+
+# === Run the Backup Process ===
+log "🔄 Starting Docker backup job"
+uptime_kuma_checkin
+
+stop_containers
+backup_directories
+start_containers
+
+cleanup_old_files
+scan_logs_for_errors
+
+log "✅ Docker backup job completed"