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.