docs: add README with setup instructions and feature overview
This commit is contained in:
Nick Heppler
parent
c82e74b72b
commit
eb0656c844
152
README.md
152
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.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user