7.3 KiB
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?
- ⚡ Quick Start
- 🧠 How it Works
- 🗂 Classification Model
- 💾 Borg Integration
- 🤖 Automation Mode
- 🔢 Exit Codes
- 🛠 Tech Stack
- 🔍 Example
- 🧱 Current Features
- 🔥 Roadmap
- 🧠 Philosophy
- 📜 License
- ❤️ 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
git clone https://github.com/YOUR-USER/dockervault.git
cd dockervault
pip install -e .
Run analysis:
python -m dockervault.cli docker-compose.yml --borg --repo /backup-repo
Run backup:
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:
python -m dockervault.cli docker-compose.yml \
--run-borg \
--repo /mnt/backups/borg/dockervault
Generated command:
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.
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
--fail-on-review
Stops automation if something needs human attention.
🛠 Tech Stack
- Python 3.10+
- PyYAML
- BorgBackup
- CLI-first design
🔍 Example
Input:
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
DockerVault is built with a clear philosophy:
simple core, intelligent behavior, and extensible design — without unnecessary complexity or vendor lock-in.
🚀 v1 — Core Engine (Current Focus)
Build a reliable, deterministic backup discovery engine
- Docker Compose scanning
- Volume and bind mount detection
- Intelligent classification (critical / review / skip)
- Backup plan generation
- Borg backup integration
- Dry-run mode
- Automation mode (
--automation,--quiet)
🔧 v2 — Observability & Automation
Make DockerVault production-ready
- Advanced logging (human + JSON output)
- Webhook support (primary notification system)
- ntfy integration (lightweight alerts)
- Email notifications (optional reports)
- Change detection (new/missing volumes)
- Backup summaries (stats, duration, warnings)
- Basic run history (file-based, no database)
🧠 v3 — Intelligence Layer
Move from tool → system awareness
- "Explain why" classification decisions
- Anomaly detection (size, duration, structure)
- System understanding confidence
- Backup diff between runs
- Smarter classification patterns
🧪 v4 — Reliability & Safety
Ensure backups are actually usable
- Restore testing (ephemeral container validation)
- Integrity checks (borg/restic verify)
- Pre/post execution hooks
- Backup profiles (critical / full / custom)
🔐 v5 — Security & Encryption
Strong, transparent data protection
- Engine-native encryption (Borg / Restic)
- Encryption validation checks
- Optional post-process encryption (age / gpg)
- Clear key handling guidelines
🔌 v6 — Plugin Ecosystem
Extend without bloating core
- Storage backends (S3, WebDAV, SSH, etc.)
- Optional cloud integrations (Dropbox, Google Drive, Proton Drive)
- Notification plugins (webhook-first approach)
- Pluggable architecture for extensions
🌐 v7 — Platform & Deployment
Make DockerVault easy to run anywhere
- Official Docker image
- Non-interactive container mode
- Unraid Community Apps template
- Configurable via environment + config file
🧭 Design Principles
- No vendor lock-in — webhook over platform integrations
- Self-hosting friendly — works fully offline/local
- Transparency over magic — explain decisions
- Stateless-first — no database required by default
- Extensible architecture — plugins over core bloat
- Backup ≠ done until restore works
🔮 Future Ideas
- Multi-host awareness (Lanx environments)
- Centralized monitoring integration (OpenObserve, etc.)
- Web UI (optional, not required)
- Automation pipelines via webhook
- Advanced reporting and visualization
Built with ❤️ for real systems — not toy setups.
🧠 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.