feat: add YAML parsing and backup detection
This commit is contained in:
Eddie Nielsen
parent
21906ff37e
commit
6c79fcc20b
2 changed files with 58 additions and 224 deletions
28
LICENSE
28
LICENSE
|
|
@ -1,15 +1,21 @@
|
||||||
GNU GENERAL PUBLIC LICENSE
|
MIT License
|
||||||
Version 2, June 1991
|
|
||||||
|
|
||||||
Copyright (C) 2026 Eddie Nielsen
|
Copyright (c) 2026 Ed & NodeFox
|
||||||
|
|
||||||
Everyone is permitted to copy and distribute verbatim copies
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||||
of this license document, but changing it is not allowed.
|
of this software and associated documentation files (the "Software"), to deal
|
||||||
|
in the Software without restriction, including without limitation the rights
|
||||||
|
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||||
|
copies of the Software, and to permit persons to whom the Software is
|
||||||
|
furnished to do so, subject to the following conditions:
|
||||||
|
|
||||||
[...]
|
The above copyright notice and this permission notice shall be included in all
|
||||||
|
copies or substantial portions of the Software.
|
||||||
(⚠️ VIGTIGT: den fulde GPL v2 tekst er meget lang — du skal bruge hele den officielle)
|
|
||||||
|
|
||||||
👉 Brug den officielle her:
|
|
||||||
https://www.gnu.org/licenses/old-licenses/gpl-2.0.txt
|
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||||
|
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||||
|
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||||
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||||
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||||
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||||
|
SOFTWARE.
|
||||||
|
|
|
||||||
254
README.md
254
README.md
|
|
@ -1,229 +1,57 @@
|
||||||
<p align="center">
|
# DockerVault
|
||||||
<img src="images/dockervault-logo.png" alt="DockerVault logo" width="600">
|
|
||||||
|
|
||||||
---
|
Early CLI foundation for DockerVault.
|
||||||
|
|
||||||
## 📑 Contents
|
## Current scope
|
||||||
|
|
||||||
* [🚀 What is DockerVault?](#-what-is-dockervault)
|
- Python CLI project skeleton
|
||||||
* [✨ Goals](#-goals)
|
- `scan` command
|
||||||
* [⚙️ Technology](#-technology)
|
- Recursive discovery of Docker Compose projects
|
||||||
* [🏗 Architecture](#-architecture)
|
- YAML parsing with `PyYAML`
|
||||||
* [📦 What DockerVault backs up](#-what-dockervault-is-expected-to-back-up)
|
- Detection of:
|
||||||
* [🔁 Restore philosophy](#-restore-philosophy)
|
- services
|
||||||
* [🧩 Planned Features](#-planned-features)
|
- images
|
||||||
* [🛣 Roadmap](#-roadmap)
|
- restart policies
|
||||||
* [📁 Project Structure](#-project-structure)
|
- bind mounts
|
||||||
* [🤝 Philosophy](#-philosophy)
|
- named volumes
|
||||||
* [📜 License](#-license)
|
- `env_file`
|
||||||
|
- JSON or human-readable output
|
||||||
|
|
||||||
---
|
## Quick start
|
||||||
|
|
||||||
## 🚀 What is DockerVault?
|
```bash
|
||||||
|
python3 -m venv .venv
|
||||||
DockerVault is a CLI-first backup system for Docker environments.
|
source .venv/bin/activate
|
||||||
|
pip install -e .
|
||||||
It is designed to make backups simple, transparent, and reliable without unnecessary complexity. The goal is to provide a practical way to discover containers, identify important data, and manage backups in a structured and predictable way.
|
|
||||||
|
|
||||||
DockerVault is aimed at homelabs, self-hosted infrastructure, and small-scale server environments where control, clarity, and recoverability matter.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ✨ Goals
|
|
||||||
|
|
||||||
DockerVault is being built to:
|
|
||||||
|
|
||||||
* Discover Docker containers automatically
|
|
||||||
* Identify volumes, bind mounts, and relevant configuration data
|
|
||||||
* Keep track of backup history and metadata
|
|
||||||
* Use a proven backup backend instead of reinventing backup logic
|
|
||||||
* Make restore operations easier and safer
|
|
||||||
* Stay simple enough to understand and debug
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## ⚙️ Technology
|
|
||||||
|
|
||||||
DockerVault is planned as a modular, CLI-first tool.
|
|
||||||
|
|
||||||
### Current design direction
|
|
||||||
|
|
||||||
* **Core language:** Python
|
|
||||||
* **Backup engine:** BorgBackup
|
|
||||||
* **Metadata storage:** SQLite
|
|
||||||
* **Interface:** CLI first
|
|
||||||
* **Platform focus:** Linux Docker hosts
|
|
||||||
|
|
||||||
### Why this stack?
|
|
||||||
|
|
||||||
* **Python** makes it fast to build, maintain, and extend
|
|
||||||
* **BorgBackup** is mature, reliable, and well-suited for deduplicated backups
|
|
||||||
* **SQLite** keeps metadata simple, local, and easy to inspect
|
|
||||||
* **CLI first** keeps the project transparent and easy to debug
|
|
||||||
|
|
||||||
The project philosophy is clear: use proven tools where it makes sense, and avoid building complexity just for the sake of it.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🏗 Architecture
|
|
||||||
|
|
||||||
DockerVault follows a simple flow:
|
|
||||||
|
|
||||||
1. Scan Docker environment
|
|
||||||
2. Detect containers, volumes, bind mounts, and configs
|
|
||||||
3. Store metadata in SQLite
|
|
||||||
4. Build backup jobs from discovered data
|
|
||||||
5. Execute backups through Borg
|
|
||||||
6. Restore data when needed
|
|
||||||
|
|
||||||
More detailed architecture notes will live in `docs/architecture.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📦 What DockerVault is expected to back up
|
|
||||||
|
|
||||||
DockerVault is intended to focus on the parts of Docker environments that actually matter:
|
|
||||||
|
|
||||||
* Docker volumes
|
|
||||||
* Bind mounts
|
|
||||||
* Selected configuration files
|
|
||||||
* Backup metadata
|
|
||||||
* Restore-related information
|
|
||||||
|
|
||||||
It is not intended to blindly copy everything without structure. The purpose is to know what is being backed up and why.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🔁 Restore philosophy
|
|
||||||
|
|
||||||
Backups are only useful if restore is realistic.
|
|
||||||
|
|
||||||
DockerVault is being designed with restore in mind from the beginning:
|
|
||||||
|
|
||||||
* Clear mapping between containers and stored data
|
|
||||||
* Metadata that explains relationships between services and data
|
|
||||||
* Predictable restore flow
|
|
||||||
* Minimal guesswork during recovery
|
|
||||||
|
|
||||||
The goal is not just to store backups, but to enable actual recovery.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🧩 Planned Features
|
|
||||||
|
|
||||||
### Core features
|
|
||||||
|
|
||||||
* Docker container discovery
|
|
||||||
* Volume detection
|
|
||||||
* Bind mount detection
|
|
||||||
* Backup job creation
|
|
||||||
* Borg-based backup execution
|
|
||||||
* SQLite-based metadata tracking
|
|
||||||
* Restore workflow
|
|
||||||
|
|
||||||
### Future possibilities
|
|
||||||
|
|
||||||
* Scheduled backups
|
|
||||||
* Retention policies
|
|
||||||
* Pre/post backup hooks
|
|
||||||
* E-mail notifications
|
|
||||||
* `ntfy` notifications
|
|
||||||
* Web interface
|
|
||||||
* Multi-node support
|
|
||||||
* Remote repository support
|
|
||||||
* Backup health/status reporting
|
|
||||||
* Configuration profiles
|
|
||||||
* Selective backup policies per container
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 🛣 Roadmap
|
|
||||||
|
|
||||||
### Phase 1 – Foundation
|
|
||||||
|
|
||||||
* Repository structure
|
|
||||||
* Documentation
|
|
||||||
* CLI skeleton
|
|
||||||
* Initial project design
|
|
||||||
|
|
||||||
### Phase 2 – Discovery
|
|
||||||
|
|
||||||
* Scan Docker environment
|
|
||||||
* Detect containers
|
|
||||||
* Detect volumes and bind mounts
|
|
||||||
|
|
||||||
### Phase 3 – Backup Engine
|
|
||||||
|
|
||||||
* Integrate BorgBackup
|
|
||||||
* Build backup job flow
|
|
||||||
* Store metadata in SQLite
|
|
||||||
|
|
||||||
### Phase 4 – Restore
|
|
||||||
|
|
||||||
* Basic restore workflow
|
|
||||||
* Restore metadata mapping
|
|
||||||
* Safer recovery process
|
|
||||||
|
|
||||||
### Phase 5 – Usability
|
|
||||||
|
|
||||||
* Better CLI commands
|
|
||||||
* Config handling
|
|
||||||
* Scheduling support
|
|
||||||
* Notifications
|
|
||||||
|
|
||||||
### Phase 6 – Expansion
|
|
||||||
|
|
||||||
* Web interface
|
|
||||||
* Multi-node support
|
|
||||||
* Advanced backup policies
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📁 Project Structure
|
|
||||||
|
|
||||||
```text
|
|
||||||
dockervault/
|
|
||||||
├── cmd/
|
|
||||||
├── core/
|
|
||||||
├── scanner/
|
|
||||||
├── backup/
|
|
||||||
├── restore/
|
|
||||||
├── config/
|
|
||||||
├── database/
|
|
||||||
├── docs/
|
|
||||||
├── scripts/
|
|
||||||
├── images/
|
|
||||||
├── README.md
|
|
||||||
└── LICENSE
|
|
||||||
```
|
```
|
||||||
|
|
||||||
---
|
Run a scan:
|
||||||
|
|
||||||
## 🤝 Philosophy
|
```bash
|
||||||
|
dockervault scan /path/to/docker/projects
|
||||||
|
```
|
||||||
|
|
||||||
DockerVault is built on a few simple principles:
|
JSON output:
|
||||||
|
|
||||||
* Keep it simple
|
```bash
|
||||||
* Be transparent
|
dockervault scan /path/to/docker/projects --json
|
||||||
* Avoid unnecessary complexity
|
```
|
||||||
* Prefer proven tools over hype
|
|
||||||
* Build something practical and maintainable
|
|
||||||
|
|
||||||
No magic. No hidden behavior. No unnecessary abstraction.
|
## What v0.2 adds
|
||||||
|
|
||||||
---
|
DockerVault no longer just finds compose files.
|
||||||
|
It now builds a first inventory layer that can be used for backup logic later:
|
||||||
|
|
||||||
Author
|
- project name and root path
|
||||||
Built with ❤️ for Lanx by NodeFox 🦊
|
- compose files found in the project
|
||||||
|
- service metadata
|
||||||
|
- backup candidate paths from bind mounts and env files
|
||||||
|
- named volumes defined in compose
|
||||||
|
|
||||||
Maintained by Eddie Nielsen Feel free to contribute, suggest improvements or fork the project.
|
## Example direction
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## 📜 License
|
|
||||||
|
|
||||||
This project is licensed under the **GNU General Public License v2.0**.
|
|
||||||
|
|
||||||
See the `LICENSE` file for details.
|
|
||||||
|
|
||||||
|
This is meant as the next brick in a bigger flow:
|
||||||
|
|
||||||
|
1. Discover Docker app folders
|
||||||
|
2. Learn what services and data paths exist
|
||||||
|
3. Later attach backup rules, Borg targets, retention, notifications, and restore metadata
|
||||||
|
|
|
||||||
Loading…
Add table
Add a link
Reference in a new issue