From 6c79fcc20b813a260f445506b19be5051e395c90 Mon Sep 17 00:00:00 2001 From: Eddie Nielsen <“ed”@edcore.dk”> Date: Sun, 22 Mar 2026 12:04:23 +0000 Subject: [PATCH] feat: add YAML parsing and backup detection --- LICENSE | 28 +++--- README.md | 254 +++++++++--------------------------------------------- 2 files changed, 58 insertions(+), 224 deletions(-) diff --git a/LICENSE b/LICENSE index c23d472..4aec557 100644 --- a/LICENSE +++ b/LICENSE @@ -1,15 +1,21 @@ -GNU GENERAL PUBLIC LICENSE -Version 2, June 1991 +MIT License -Copyright (C) 2026 Eddie Nielsen +Copyright (c) 2026 Ed & NodeFox -Everyone is permitted to copy and distribute verbatim copies -of this license document, but changing it is not allowed. +Permission is hereby granted, free of charge, to any person obtaining a copy +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: -[...] - -(⚠️ 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 above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. +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. diff --git a/README.md b/README.md index 457ae8d..ab0cda8 100644 --- a/README.md +++ b/README.md @@ -1,229 +1,57 @@ -

- DockerVault logo +# DockerVault ---- +Early CLI foundation for DockerVault. -## 📑 Contents +## Current scope -* [🚀 What is DockerVault?](#-what-is-dockervault) -* [✨ Goals](#-goals) -* [⚙️ Technology](#-technology) -* [🏗 Architecture](#-architecture) -* [📦 What DockerVault backs up](#-what-dockervault-is-expected-to-back-up) -* [🔁 Restore philosophy](#-restore-philosophy) -* [🧩 Planned Features](#-planned-features) -* [🛣 Roadmap](#-roadmap) -* [📁 Project Structure](#-project-structure) -* [🤝 Philosophy](#-philosophy) -* [📜 License](#-license) +- Python CLI project skeleton +- `scan` command +- Recursive discovery of Docker Compose projects +- YAML parsing with `PyYAML` +- Detection of: + - services + - images + - restart policies + - bind mounts + - named volumes + - `env_file` +- JSON or human-readable output ---- +## Quick start -## 🚀 What is DockerVault? - -DockerVault is a CLI-first backup system for Docker environments. - -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 +```bash +python3 -m venv .venv +source .venv/bin/activate +pip install -e . ``` ---- +Run a scan: -## 🤝 Philosophy +```bash +dockervault scan /path/to/docker/projects +``` -DockerVault is built on a few simple principles: +JSON output: -* Keep it simple -* Be transparent -* Avoid unnecessary complexity -* Prefer proven tools over hype -* Build something practical and maintainable +```bash +dockervault scan /path/to/docker/projects --json +``` -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 -Built with ❤️ for Lanx by NodeFox 🦊 +- project name and root path +- 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. - ---- - -## 📜 License - -This project is licensed under the **GNU General Public License v2.0**. - -See the `LICENSE` file for details. +## Example direction +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