307 lines
4.7 KiB
Markdown
307 lines
4.7 KiB
Markdown
<p align="center">
|
|
<img src="images/dockervault_logo.png" width="600">
|
|
</p>
|
|
|
|
# DockerVault
|
|
|
|
> Intelligent Docker backup discovery for real systems
|
|
|
|
DockerVault scans your Docker environments and figures out **what actually matters to back up** — automatically.
|
|
|
|
No guesswork. No forgotten volumes. No broken restores.
|
|
|
|
---
|
|
|
|
## 📚 Contents
|
|
|
|
* [🚀 What is DockerVault?](#-what-is-dockervault)
|
|
* [⚡ Quick Start](#-quick-start)
|
|
* [🧠 How it Works](#-how-it-works)
|
|
* [🗂 Classification Model](#-classification-model)
|
|
* [💾 Borg Integration](#-borg-integration)
|
|
* [🤖 Automation Mode](#-automation-mode)
|
|
* [🔢 Exit Codes](#-exit-codes)
|
|
* [🛠 Tech Stack](#-tech-stack)
|
|
* [🔍 Example](#-example)
|
|
* [🧱 Current Features](#-current-features)
|
|
* [🔥 Roadmap](#-roadmap)
|
|
* [🧠 Philosophy](#-philosophy)
|
|
* [📜 License](#-license)
|
|
* [❤️ Credits](#-credits)
|
|
|
|
---
|
|
|
|
## 🚀 What is DockerVault?
|
|
|
|
DockerVault analyzes your `docker-compose.yml` and identifies:
|
|
|
|
* What **must** be backed up
|
|
* What can be **ignored**
|
|
* What needs **human review**
|
|
|
|
It bridges the gap between:
|
|
|
|
👉 “everything looks fine”
|
|
and
|
|
👉 “restore just failed”
|
|
|
|
---
|
|
|
|
## ⚡ Quick Start
|
|
|
|
```bash
|
|
git clone https://github.com/YOUR-USER/dockervault.git
|
|
cd dockervault
|
|
|
|
pip install -e .
|
|
```
|
|
|
|
Run analysis:
|
|
|
|
```bash
|
|
python -m dockervault.cli docker-compose.yml --borg --repo /backup-repo
|
|
```
|
|
|
|
Run backup:
|
|
|
|
```bash
|
|
python -m dockervault.cli docker-compose.yml \
|
|
--run-borg \
|
|
--repo /backup-repo
|
|
```
|
|
|
|
---
|
|
|
|
## 🧠 How it Works
|
|
|
|
DockerVault parses your compose file and inspects:
|
|
|
|
* bind mounts
|
|
* volume targets
|
|
* known data paths
|
|
|
|
It then classifies them using heuristics:
|
|
|
|
* database paths → critical
|
|
* logs/cache → optional
|
|
* unknown → review
|
|
|
|
---
|
|
|
|
## 🗂 Classification Model
|
|
|
|
DockerVault divides everything into three categories:
|
|
|
|
### ✅ INCLUDE
|
|
|
|
Must be backed up.
|
|
|
|
Example:
|
|
|
|
```
|
|
/var/lib/mysql
|
|
/data
|
|
/config
|
|
```
|
|
|
|
### ⚠️ REVIEW
|
|
|
|
Needs human decision.
|
|
|
|
Triggered when:
|
|
|
|
* path does not exist
|
|
* path exists but is empty
|
|
* named volumes (Docker-managed)
|
|
|
|
Example:
|
|
|
|
```
|
|
./mc-missing → /data
|
|
```
|
|
|
|
### ❌ SKIP
|
|
|
|
Safe to ignore.
|
|
|
|
Example:
|
|
|
|
```
|
|
/var/log
|
|
/tmp
|
|
/cache
|
|
```
|
|
|
|
---
|
|
|
|
## 💾 Borg Integration
|
|
|
|
DockerVault can generate and run Borg backups directly.
|
|
|
|
Example:
|
|
|
|
```bash
|
|
python -m dockervault.cli docker-compose.yml \
|
|
--run-borg \
|
|
--repo /mnt/backups/borg/dockervault
|
|
```
|
|
|
|
Generated command:
|
|
|
|
```bash
|
|
borg create --stats --progress \
|
|
/repo::hostname-2026-03-23_12-44-19 \
|
|
/path/to/data
|
|
```
|
|
|
|
### Features
|
|
|
|
* automatic archive naming (with seconds precision)
|
|
* deduplicated paths
|
|
* safe command generation
|
|
* subprocess execution
|
|
* optional passphrase support
|
|
|
|
---
|
|
|
|
## 🤖 Automation Mode
|
|
|
|
Designed for cron / scripts / servers.
|
|
|
|
```bash
|
|
python -m dockervault.cli docker-compose.yml \
|
|
--run-borg \
|
|
--quiet \
|
|
--automation \
|
|
--repo /backup-repo
|
|
```
|
|
|
|
### Behavior
|
|
|
|
* no plan output
|
|
* no interactive prompts
|
|
* minimal output
|
|
* suitable for logs / CI
|
|
|
|
---
|
|
|
|
## 🔢 Exit Codes
|
|
|
|
| Code | Meaning |
|
|
| ---- | ------------------------------------ |
|
|
| 0 | Success |
|
|
| 1 | General error |
|
|
| 2 | Missing required args |
|
|
| 3 | No include paths |
|
|
| 4 | Review required (`--fail-on-review`) |
|
|
|
|
### Fail on review
|
|
|
|
```bash
|
|
--fail-on-review
|
|
```
|
|
|
|
Stops automation if something needs human attention.
|
|
|
|
---
|
|
|
|
## 🛠 Tech Stack
|
|
|
|
* Python 3.10+
|
|
* PyYAML
|
|
* BorgBackup
|
|
* CLI-first design
|
|
|
|
---
|
|
|
|
## 🔍 Example
|
|
|
|
Input:
|
|
|
|
```yaml
|
|
services:
|
|
db:
|
|
volumes:
|
|
- ./db:/var/lib/mysql
|
|
|
|
mc:
|
|
volumes:
|
|
- ./mc-missing:/data
|
|
|
|
nginx:
|
|
volumes:
|
|
- ./logs:/var/log/nginx
|
|
```
|
|
|
|
Output:
|
|
|
|
```
|
|
INCLUDE:
|
|
db
|
|
|
|
REVIEW:
|
|
mc-missing
|
|
|
|
SKIP:
|
|
logs
|
|
```
|
|
|
|
---
|
|
|
|
## 🧱 Current Features
|
|
|
|
* Docker Compose parsing
|
|
* Bind mount detection
|
|
* Intelligent classification
|
|
* Borg backup integration
|
|
* Automation mode
|
|
* Exit codes for scripting
|
|
* Safe path handling
|
|
* Deduplication
|
|
|
|
---
|
|
|
|
## 🔥 Roadmap
|
|
|
|
* [ ] Named volume inspection (`docker volume inspect`)
|
|
* [ ] Docker API integration
|
|
* [ ] Multiple compose files support
|
|
* [ ] Email / ntfy notifications
|
|
* [ ] Web interface
|
|
* [ ] Backup history tracking
|
|
* [ ] Restore validation
|
|
* [ ] Scheduling integration
|
|
|
|
---
|
|
|
|
## 🧠 Philosophy
|
|
|
|
DockerVault is built on a simple idea:
|
|
|
|
> Backups should reflect reality — not assumptions.
|
|
|
|
* No blind backups
|
|
* No hidden data
|
|
* No silent failures
|
|
|
|
Just clarity.
|
|
|
|
---
|
|
|
|
## 📜 License
|
|
|
|
GNU GPLv3
|
|
|
|
This project is free software: you can redistribute it and/or modify
|
|
it under the terms of the GNU General Public License v3.
|
|
|
|
---
|
|
|
|
## ❤️ Credits
|
|
|
|
Created by **Ed & NodeFox 🦊**
|
|
|
|
Built with ❤️ for Lanx
|
|
|
|
Maintained by Eddie Nielsen
|
|
Feel free to contribute, suggest improvements or fork the project.
|