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
|
||||
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.
|
||||
|
|
|
|||
254
README.md
254
README.md
|
|
@ -1,229 +1,57 @@
|
|||
<p align="center">
|
||||
<img src="images/dockervault-logo.png" alt="DockerVault logo" width="600">
|
||||
# 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
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue