mirror of
https://github.com/kevinveenbirkenbach/docker-volume-backup-cleanup.git
synced 2025-12-31 04:29:08 +00:00
Kevin Veen-Birkenbach
5e768d9824
- migrate to pyproject.toml and pip installation - introduce cleanback CLI entrypoint - add unit and Docker-based end-to-end tests - unify GitHub Actions CI and stable tagging - remove legacy tests.yml and pkgmgr requirements https://chatgpt.com/share/69517d20-f850-800f-b6ff-6b983247888f
153 lines
3.7 KiB
Markdown
153 lines
3.7 KiB
Markdown
# Cleanup Failed Backups (cleanback) 🚮⚡
|
|
|
|
[](https://github.com/sponsors/kevinveenbirkenbach)
|
|
[](https://www.patreon.com/c/kevinveenbirkenbach)
|
|
[](https://buymeacoffee.com/kevinveenbirkenbach)
|
|
[](https://s.veen.world/paypaldonate)
|
|
|
|
**Repository:** https://github.com/kevinveenbirkenbach/cleanup-failed-backups
|
|
|
|
`cleanback` validates and (optionally) cleans up **failed Docker backup directories**.
|
|
It scans backup folders under `/Backups`, uses :contentReference[oaicite:0]{index=0} to validate each subdirectory, and lets you delete the ones that fail validation.
|
|
|
|
Validation runs **in parallel** for performance; deletions are controlled and can be **interactive** or **fully automatic**.
|
|
|
|
---
|
|
|
|
## ✨ Highlights
|
|
|
|
- **Parallel validation** of backup subdirectories
|
|
- Uses **`dirval`** (directory-validator) via CLI
|
|
- **Interactive** or **non-interactive** deletion flow (`--yes`)
|
|
- Supports validating a single backup **ID** or **all** backups
|
|
- Clean **Python package** with `pyproject.toml`
|
|
- **Unit + Docker-based E2E tests**
|
|
|
|
---
|
|
|
|
## 📦 Installation
|
|
|
|
### Via pip (recommended)
|
|
|
|
```bash
|
|
pip install cleanback
|
|
````
|
|
|
|
This installs:
|
|
|
|
* the `cleanback` CLI
|
|
* `dirval` as a dependency (declared in `pyproject.toml`)
|
|
|
|
### Editable install (for development)
|
|
|
|
```bash
|
|
git clone https://github.com/kevinveenbirkenbach/cleanup-failed-backups
|
|
cd cleanup-failed-backups
|
|
pip install -e .
|
|
```
|
|
|
|
---
|
|
|
|
## 🔧 Requirements
|
|
|
|
* Python **3.8+**
|
|
* Access to the `/Backups` directory tree
|
|
* `dirval` (installed automatically via pip dependency)
|
|
|
|
---
|
|
|
|
## 🚀 Usage
|
|
|
|
### CLI entrypoint
|
|
|
|
After installation, the command is:
|
|
|
|
```bash
|
|
cleanback
|
|
```
|
|
|
|
### Validate a single backup ID
|
|
|
|
```bash
|
|
cleanback --id <ID>
|
|
```
|
|
|
|
Validates directories under:
|
|
|
|
```
|
|
/Backups/<ID>/backup-docker-to-local/*
|
|
```
|
|
|
|
### Validate all backups
|
|
|
|
```bash
|
|
cleanback --all
|
|
```
|
|
|
|
Scans:
|
|
|
|
```
|
|
/Backups/*/backup-docker-to-local/*
|
|
```
|
|
|
|
---
|
|
|
|
### Common options
|
|
|
|
| Option | Description |
|
|
| -------------------- | ------------------------------------------------------------------ |
|
|
| `--dirval-cmd <cmd>` | Path or name of `dirval` executable (default: `dirval`) |
|
|
| `--workers <n>` | Parallel workers (default: CPU count, min 2) |
|
|
| `--timeout <sec>` | Per-directory validation timeout (float supported, default: 300.0) |
|
|
| `--yes` | Non-interactive mode: delete failures automatically |
|
|
|
|
---
|
|
|
|
### Examples
|
|
|
|
```bash
|
|
# Validate a single backup and prompt on failures
|
|
cleanback --id 2024-09-01T12-00-00
|
|
|
|
# Validate everything with 8 workers and auto-delete failures
|
|
cleanback --all --workers 8 --yes
|
|
|
|
# Use a custom dirval binary and short timeout
|
|
cleanback --all --dirval-cmd /usr/local/bin/dirval --timeout 5.0
|
|
```
|
|
|
|
---
|
|
|
|
## 🧪 Tests
|
|
|
|
### Run all tests
|
|
|
|
```bash
|
|
make test
|
|
```
|
|
|
|
---
|
|
|
|
## 🔒 Safety & Design Notes
|
|
|
|
* **No host filesystem is modified** during tests
|
|
(E2E tests run exclusively inside Docker)
|
|
* Deletions are **explicitly confirmed** unless `--yes` is used
|
|
* Timeouts are treated as **validation failures**
|
|
* Validation and deletion phases are **clearly separated**
|
|
|
|
---
|
|
|
|
## 🪪 License
|
|
|
|
This project is licensed under the **GNU Affero General Public License v3.0**.
|
|
See the [LICENSE](LICENSE) file for details.
|
|
|
|
---
|
|
|
|
## 👤 Author
|
|
|
|
**Kevin Veen-Birkenbach**
|
|
🌐 [https://www.veen.world](https://www.veen.world)
|
|
📧 [kevin@veen.world](mailto:kevin@veen.world)
|