dockervault/README.md

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

• 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.