backup-docker-to-local 1.0.0__py3-none-any.whl

backup_docker_to_local-1.0.0.dist-info/METADATA

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: backup-docker-to-local
+Version: 1.0.0
+Summary: Backup Docker volumes to local with rsync and optional DB dumps.
+Author: Kevin Veen-Birkenbach
+License: AGPL-3.0-or-later
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: dirval
+Dynamic: license-file
+
+# baudolo – Deterministic Backup & Restore for Docker Volumes 📦🔄
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate) [![License: AGPL v3](https://img.shields.io/badge/License-AGPL%20v3-blue.svg)](https://www.gnu.org/licenses/agpl-3.0) [![Docker Version](https://img.shields.io/badge/Docker-Yes-blue.svg)](https://www.docker.com) [![Python Version](https://img.shields.io/badge/Python-3.x-blue.svg)](https://www.python.org) [![GitHub stars](https://img.shields.io/github/stars/kevinveenbirkenbach/backup-docker-to-local.svg?style=social)](https://github.com/kevinveenbirkenbach/backup-docker-to-local/stargazers)
+
+
+`baudolo` is a backup and restore system for Docker volumes with
+**mandatory file backups** and **explicit, deterministic database dumps**.
+It is designed for environments with many Docker services where:
+- file-level backups must always exist
+- database dumps must be intentional, predictable, and auditable
+
+## ✨ Key Features
+
+- 📦 Incremental Docker volume backups using `rsync --link-dest`
+- 🗄 Optional SQL dumps for:
+  - PostgreSQL
+  - MariaDB / MySQL
+- 🌱 Explicit database definition for SQL backups (no auto-discovery)
+- 🧾 Backup integrity stamping via `dirval` (Python API)
+- ⏸ Automatic container stop/start when required for consistency
+- 🚫 Whitelisting of containers that do not require stopping
+- ♻️ Modular, maintainable Python architecture
+
+
+## 🧠 Core Concept (Important!)
+
+`baudolo` **separates file backups from database dumps**.
+
+- **Docker volumes are always backed up at file level**
+- **SQL dumps are created only for explicitly defined databases**
+
+This results in the following behavior:
+
+| Database defined | File backup | SQL dump |
+|------------------|-------------|----------|
+| No               | ✔ yes       | ✘ no     |
+| Yes              | ✔ yes       | ✔ yes    |
+
+## 📁 Backup Layout
+
+Backups are stored in a deterministic, fully nested structure:
+
+```text
+<backups-dir>/
+└── <machine-hash>/
+    └── <repo-name>/
+        └── <timestamp>/
+            └── <volume-name>/
+                ├── files/
+                └── sql/
+                    └── <database>.backup.sql
+```
+
+### Meaning of each level
+
+* `<machine-hash>`
+  SHA256 hash of `/etc/machine-id` (host separation)
+
+* `<repo-name>`
+  Logical backup namespace (project / stack)
+
+* `<timestamp>`
+  Backup generation (`YYYYMMDDHHMMSS`)
+
+* `<volume-name>`
+  Docker volume name
+
+* `files/`
+  Incremental file backup (rsync)
+
+* `sql/`
+  Optional SQL dumps (only for defined databases)
+
+## 🚀 Installation
+
+### Local (editable install)
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+pip install -e .
+```
+
+## 🌱 Database Definition (SQL Backup Scope)
+
+### How SQL backups are defined
+
+`baudolo` creates SQL dumps **only** for databases that are **explicitly defined**
+via configuration (e.g. a databases definition file or seeding step).
+
+If a database is **not defined**:
+
+* its Docker volume is still backed up (files)
+* **no SQL dump is created**
+
+> No database definition → file backup only
+> Database definition present → file backup + SQL dump
+
+### Why explicit definition?
+
+`baudolo` does **not** inspect running containers to guess databases.
+
+Databases must be explicitly defined to guarantee:
+
+* deterministic backups
+* predictable restore behavior
+* reproducible environments
+* zero accidental production data exposure
+
+### Required database metadata
+
+Each database definition provides:
+
+* database instance (container or logical instance)
+* database name
+* database user
+* database password
+
+This information is used by `baudolo` to execute
+`pg_dump`, `pg_dumpall`, or `mariadb-dump`.
+
+## 💾 Running a Backup
+
+```bash
+baudolo \
+  --compose-dir /srv/docker \
+  --databases-csv /etc/baudolo/databases.csv \
+  --database-containers central-postgres central-mariadb \
+  --images-no-stop-required alpine postgres mariadb mysql \
+  --images-no-backup-required redis busybox
+```
+
+### Common Backup Flags
+
+| Flag            | Description                                 |
+| --------------- | ------------------------------------------- |
+| `--everything`  | Always stop containers and re-run rsync     |
+| `--dump-only`   | Only create SQL dumps, skip file backups    |
+| `--shutdown`    | Do not restart containers after backup      |
+| `--backups-dir` | Backup root directory (default: `/Backups`) |
+| `--repo-name`   | Backup namespace under machine hash         |
+
+## ♻️ Restore Operations
+
+### Restore Volume Files
+
+```bash
+baudolo-restore files \
+  my-volume \
+  <machine-hash> \
+  <version> \
+  --backups-dir /Backups \
+  --repo-name my-repo
+```
+
+Restore into a **different target volume**:
+
+```bash
+baudolo-restore files \
+  target-volume \
+  <machine-hash> \
+  <version> \
+  --source-volume source-volume
+```
+
+### Restore PostgreSQL
+
+```bash
+baudolo-restore postgres \
+  my-volume \
+  <machine-hash> \
+  <version> \
+  --container postgres \
+  --db-name appdb \
+  --db-password secret \
+  --empty
+```
+
+### Restore MariaDB / MySQL
+
+```bash
+baudolo-restore mariadb \
+  my-volume \
+  <machine-hash> \
+  <version> \
+  --container mariadb \
+  --db-name shopdb \
+  --db-password secret \
+  --empty
+```
+
+> `baudolo` automatically detects whether `mariadb` or `mysql`
+> is available inside the container
+
+## 🔍 Backup Scheme
+
+The backup mechanism uses incremental backups with rsync and stamps directories with a unique hash. For more details on the backup scheme, check out [this blog post](https://blog.veen.world/blog/2020/12/26/how-i-backup-dedicated-root-servers/).  
+![Backup Scheme](https://blog.veen.world/wp-content/uploads/2020/12/server-backup-1024x755.jpg)
+
+## 👨‍💻 Author
+
+**Kevin Veen-Birkenbach**  
+- 📧 [kevin@veen.world](mailto:kevin@veen.world)  
+- 🌐 [https://www.veen.world/](https://www.veen.world/)
+
+## 📜 License
+
+This project is licensed under the **GNU Affero General Public License v3.0**. See the [LICENSE](./LICENSE) file for details.
+
+## 🔗 More Information
+
+- [Docker Volumes Documentation](https://docs.docker.com/storage/volumes/)
+- [Docker Backup Volumes Blog](https://blog.ssdnodes.com/blog/docker-backup-volumes/)
+- [Backup Strategies](https://en.wikipedia.org/wiki/Incremental_backup#Incremental)
+
+---
+
+Happy Backing Up! 🚀🔐

backup_docker_to_local-1.0.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+backup_docker_to_local-1.0.0.dist-info/licenses/LICENSE,sha256=hIahDEOTzuHCU5J2nd07LWwkLW7Hko4UFO__ffsvB-8,34523
+baudolo/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+baudolo/backup/__init__.py,sha256=5BfF8JBXB2j6sAptcmswtbjlajNWxOho6_CjwIamO7k,30
+baudolo/backup/__main__.py,sha256=118gZ0wij9_PAtR-jlG7LizrhrxwhHlAcAPW1eFeJtU,140
+baudolo/backup/app.py,sha256=eZJ0Y1LYZ_NiYw-nzb-h7-x-5AbZFsCjqsP127Mfy-I,5796
+baudolo/backup/cli.py,sha256=u-lQyfbPPiZOnOQ8ugS5yeXHfRVLBOGOw40iOUsOd5s,2619
+baudolo/backup/compose.py,sha256=LKwMzfroKML0miZqJzzhXN3SMm07Ry_85l3p4B0cqeo,1130
+baudolo/backup/db.py,sha256=hNL08pV0osNrOBD3k_EhP8boawRWTc7QlpIPEKitD-E,2402
+baudolo/backup/docker.py,sha256=QxP8C-O7glWrOvZnhELI4-8E2vz_xXEy0CM8QeW8u3k,1342
+baudolo/backup/shell.py,sha256=guMHWcRb0Qlrz79gqFqmJLXVQK8cJEvNkhkMe5Tpgwc,738
+baudolo/backup/volume.py,sha256=_bz-G0HLdDETnWuiAB-geb5xbEaLLsxs9uPFK0lsADc,1449
+baudolo/restore/__init__.py,sha256=qGPo54bmX0D1TRuP22sTQXhpOOwTa8BheEq8aWKsWOk,18
+baudolo/restore/__main__.py,sha256=c0u0YS7xqLRxn9gsvXvorlU8jbs4LlSDxU7JiBAtdIk,5083
+baudolo/restore/files.py,sha256=vV2M60i3-9rwLFV1Kb1Fc_m1SXYYOFUEPQKCMnlOpo4,1031
+baudolo/restore/paths.py,sha256=fcM-39loVXsi-0qgG2FxFmYh3R748Ss5CJqnZinKcNE,708
+baudolo/restore/run.py,sha256=rai5F27D6F8RRnFMyjcEGiHBAlVXtMOJoazs6zkLSC0,2302
+baudolo/restore/db/__init__.py,sha256=9NfiJvVx-sIJfLuZYnOHGjunpbFyqGZSqISFgLTcP5o,58
+baudolo/restore/db/mariadb.py,sha256=0sk6eJiDDr-knIEQyqQIHNtRt7AQrqRlOlnOijVVLno,2516
+baudolo/restore/db/postgres.py,sha256=_NIlcxdpcQIUZ8SNBWfWIaH1oGIkmZy9emFMgjGznhk,1446
+baudolo/seed/__main__.py,sha256=yVWzODjWLBtRVNTOrZNZTV8pBNm6LGWGNKAe7lrJVa8,1874
+backup_docker_to_local-1.0.0.dist-info/METADATA,sha256=XsXf4_FpX_PECc1oJKU4rKgkVsjWuzPuxjz_a5JVPLM,7116
+backup_docker_to_local-1.0.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+backup_docker_to_local-1.0.0.dist-info/entry_points.txt,sha256=92f5jPSjW__9-u5gzwmWkdiHKt4ysEFCVmwMtorQCv4,147
+backup_docker_to_local-1.0.0.dist-info/top_level.txt,sha256=y_5iNpF7EdLzqWWXIDfcTJpqijyy2hvrYgNiJXrN4r4,8
+backup_docker_to_local-1.0.0.dist-info/RECORD,,

backup_docker_to_local-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

backup_docker_to_local-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,4 @@
+[console_scripts]
+baudolo = baudolo.backup.__main__:main
+baudolo-restore = baudolo.restore.__main__:main
+baudolo-seed = baudolo.seed.__main__:main