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