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
• 🔮 Future Ideas
• 🧠 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

Ideas that push DockerVault beyond backup — towards system awareness and control.

🧠 System Intelligence

• Change detection (new/missing volumes, structure changes)
• "Explain why" classification decisions
• System understanding confidence score
• Backup diff between runs
• Detection of unknown/unclassified data

📊 Observability & Insight

• Historical trends (size, duration, change rate)
• Growth analysis (detect abnormal data expansion)
• Backup performance tracking
• Structured JSON logs for external systems

🚨 Alerting & Automation

• Webhook-first automation triggers
• ntfy notifications
• Email reporting
• Conditional alerts (failures, anomalies, missing data)
• Integration with external systems (Node-RED, Home Assistant, OpenObserve)

🧪 Reliability & Verification

• Automated restore testing (ephemeral containers)
• Service-level validation (DB start, app health)
• Integrity checks (borg/restic verification)
• Backup validation reports

⚙️ Control & Extensibility

• Pre/post execution hooks
• Backup profiles (critical / full / custom)
• Simulation mode (predict behavior before execution)
• Advanced dry-run with diff preview

🔐 Security & Encryption

• Engine-native encryption support
• Optional post-process encryption (age, gpg)
• Encryption validation and key awareness
• Secure offsite export workflows

🔌 Plugin Ecosystem

• Storage backends (S3, WebDAV, SSH, etc.)
• Optional cloud targets (Dropbox, Google Drive, Proton Drive)
• Notification plugins (webhook-first design)
• Pluggable architecture for extensions

🌐 Multi-System Awareness

• Multi-host environments (Lanx-style setups)
• Centralized reporting and monitoring
• Cross-node backup visibility

🖥 Platform & UX

• Optional Web UI (status, history, alerts)
• Docker-native deployment mode
• Unraid Community Apps integration
• Config-driven operation (env + config files)

---

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 Nielsen https://lanx.dk
NodeFox 🦊 https://nodefox.lanx.dk

Built with ❤️ for Lanx

Maintained by Ed Nielsen Feel free to contribute, suggest improvements or fork the project.