refactor: migrate to src/ package + add DinD-based E2E runner with debug artifacts

- Replace legacy standalone scripts with a proper src-layout Python package
  (baudolo backup/restore/configure entrypoints via pyproject.toml)
- Remove old scripts/files (backup-docker-to-local.py, recover-docker-from-local.sh,
  databases.csv.tpl, Todo.md)
- Add Dockerfile to build the project image for local/E2E usage
- Update Makefile: build image and run E2E via external runner script
- Add scripts/test-e2e.sh:
  - start DinD + dedicated network
  - recreate DinD data volume (and shared /tmp volume)
  - pre-pull helper images (alpine-rsync, alpine)
  - load local baudolo:local image into DinD
  - run unittest E2E suite inside DinD and abort on first failure
  - on failure: dump host+DinD diagnostics and archive shared /tmp into artifacts/
- Add artifacts/ debug outputs produced by failing E2E runs (logs, events, tmp archive)

https://chatgpt.com/share/694ec23f-0794-800f-9a59-8365bc80f435

src/baudolo/backup/__init__.py

@@ -0,0 +1 @@
+"""Baudolo backup package."""

src/baudolo/backup/__main__.py

@@ -0,0 +1,9 @@
+#!/usr/bin/env python3
+
+from __future__ import annotations
+
+from .app import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/baudolo/backup/app.py

@@ -0,0 +1,183 @@
+from __future__ import annotations
+
+import os
+import pathlib
+from datetime import datetime
+
+import pandas
+from dirval import create_stamp_file
+
+from .cli import parse_args
+from .compose import handle_docker_compose_services
+from .db import backup_database
+from .docker import (
+    change_containers_status,
+    containers_using_volume,
+    docker_volume_names,
+    get_image_info,
+    has_image,
+)
+from .shell import execute_shell_command
+from .volume import backup_volume
+
+
+def get_machine_id() -> str:
+    return execute_shell_command("sha256sum /etc/machine-id")[0][0:64]
+
+
+def stamp_directory(version_dir: str) -> None:
+    """
+    Use dirval as a Python library to stamp the directory (no CLI dependency).
+    """
+    create_stamp_file(version_dir)
+
+
+def create_version_directory(versions_dir: str, backup_time: str) -> str:
+    version_dir = os.path.join(versions_dir, backup_time)
+    pathlib.Path(version_dir).mkdir(parents=True, exist_ok=True)
+    return version_dir
+
+
+def create_volume_directory(version_dir: str, volume_name: str) -> str:
+    path = os.path.join(version_dir, volume_name)
+    pathlib.Path(path).mkdir(parents=True, exist_ok=True)
+    return path
+
+
+def is_image_ignored(container: str, images_no_backup_required: list[str]) -> bool:
+    if not images_no_backup_required:
+        return False
+    img = get_image_info(container)
+    return any(pat in img for pat in images_no_backup_required)
+
+
+def volume_is_fully_ignored(containers: list[str], images_no_backup_required: list[str]) -> bool:
+    """
+    Skip file backup only if all containers linked to the volume are ignored.
+    """
+    if not containers:
+        return False
+    return all(is_image_ignored(c, images_no_backup_required) for c in containers)
+
+
+def requires_stop(containers: list[str], images_no_stop_required: list[str]) -> bool:
+    """
+    Stop is required if ANY container image is NOT in the whitelist patterns.
+    """
+    for c in containers:
+        img = get_image_info(c)
+        if not any(pat in img for pat in images_no_stop_required):
+            return True
+    return False
+
+
+def backup_mariadb_or_postgres(
+    *,
+    container: str,
+    volume_dir: str,
+    databases_df: "pandas.DataFrame",
+    database_containers: list[str],
+) -> bool:
+    """
+    Returns True if the container is a DB container we handled.
+    """
+    for img in ["mariadb", "postgres"]:
+        if has_image(container, img):
+            backup_database(
+                container=container,
+                volume_dir=volume_dir,
+                db_type=img,
+                databases_df=databases_df,
+                database_containers=database_containers,
+            )
+            return True
+    return False
+
+
+def _backup_dumps_for_volume(
+    *,
+    containers: list[str],
+    vol_dir: str,
+    databases_df: "pandas.DataFrame",
+    database_containers: list[str],
+) -> bool:
+    """
+    Create DB dumps for any mariadb/postgres containers attached to this volume.
+    Returns True if at least one dump was produced.
+    """
+    dumped_any = False
+    for c in containers:
+        if backup_mariadb_or_postgres(
+            container=c,
+            volume_dir=vol_dir,
+            databases_df=databases_df,
+            database_containers=database_containers,
+        ):
+            dumped_any = True
+    return dumped_any
+
+
+def main() -> int:
+    args = parse_args()
+
+    machine_id = get_machine_id()
+    backup_time = datetime.now().strftime("%Y%m%d%H%M%S")
+
+    versions_dir = os.path.join(args.backups_dir, machine_id, args.repo_name)
+    version_dir = create_version_directory(versions_dir, backup_time)
+
+    databases_df = pandas.read_csv(args.databases_csv, sep=";")
+
+    print("💾 Start volume backups...", flush=True)
+
+    for volume_name in docker_volume_names():
+        print(f"Start backup routine for volume: {volume_name}", flush=True)
+        containers = containers_using_volume(volume_name)
+
+        vol_dir = create_volume_directory(version_dir, volume_name)
+
+        # Old behavior: DB dumps are additional to file backups.
+        _backup_dumps_for_volume(
+            containers=containers,
+            vol_dir=vol_dir,
+            databases_df=databases_df,
+            database_containers=args.database_containers,
+        )
+
+        # dump-only: skip ALL file rsync backups
+        if args.dump_only:
+            continue
+
+        # skip file backup if all linked containers are ignored
+        if volume_is_fully_ignored(containers, args.images_no_backup_required):
+            print(
+                f"Skipping file backup for volume '{volume_name}' (all linked containers are ignored).",
+                flush=True,
+            )
+            continue
+
+        if args.everything:
+            # "everything": always do pre-rsync, then stop + rsync again
+            backup_volume(versions_dir, volume_name, vol_dir)
+            change_containers_status(containers, "stop")
+            backup_volume(versions_dir, volume_name, vol_dir)
+            if not args.shutdown:
+                change_containers_status(containers, "start")
+            continue
+
+        # default: rsync, and if needed stop + rsync
+        backup_volume(versions_dir, volume_name, vol_dir)
+        if requires_stop(containers, args.images_no_stop_required):
+            change_containers_status(containers, "stop")
+            backup_volume(versions_dir, volume_name, vol_dir)
+            if not args.shutdown:
+                change_containers_status(containers, "start")
+
+    # Stamp the backup version directory using dirval (python lib)
+    stamp_directory(version_dir)
+    print("Finished volume backups.", flush=True)
+
+    print("Handling Docker Compose services...", flush=True)
+    handle_docker_compose_services(args.compose_dir, args.docker_compose_hard_restart_required)
+
+    return 0

src/baudolo/backup/cli.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+import argparse
+import os
+from pathlib import Path
+
+
+def _default_repo_name() -> str:
+    """
+    Derive the repository name from the folder that contains `src/`.
+
+    Expected layout:
+      <repo-root>/src/baudolo/backup/cli.py
+
+    => parents[0]=backup, [1]=baudolo, [2]=src, [3]=repo-root
+    """
+    try:
+        return Path(__file__).resolve().parents[3].name
+    except Exception:
+        return "backup-docker-to-local"
+
+
+def parse_args() -> argparse.Namespace:
+    dirname = os.path.dirname(__file__)
+    default_databases_csv = os.path.join(dirname, "databases.csv")
+
+    p = argparse.ArgumentParser(description="Backup Docker volumes.")
+
+    p.add_argument(
+        "--compose-dir",
+        type=str,
+        required=True,
+        help="Path to the parent directory containing docker-compose setups",
+    )
+    p.add_argument(
+        "--docker-compose-hard-restart-required",
+        nargs="+",
+        default=["mailu"],
+        help="Compose dir names that require 'docker-compose down && up -d' (default: mailu)",
+    )
+
+    p.add_argument(
+        "--repo-name",
+        default=_default_repo_name(),
+        help="Backup repo folder name under <backups-dir>/<machine-id>/ (default: git repo folder name)",
+    )
+    p.add_argument(
+        "--databases-csv",
+        default=default_databases_csv,
+        help=f"Path to databases.csv (default: {default_databases_csv})",
+    )
+    p.add_argument(
+        "--backups-dir",
+        default="/Backups",
+        help="Backup root directory (default: /Backups)",
+    )
+
+    p.add_argument(
+        "--database-containers",
+        nargs="+",
+        required=True,
+        help="Container names treated as special instances for database backups",
+    )
+    p.add_argument(
+        "--images-no-stop-required",
+        nargs="+",
+        required=True,
+        help="Image name patterns for which containers should not be stopped during file backup",
+    )
+    p.add_argument(
+        "--images-no-backup-required",
+        nargs="+",
+        default=[],
+        help="Image name patterns for which no backup should be performed",
+    )
+
+    p.add_argument(
+        "--everything",
+        action="store_true",
+        help="Force file backup for all volumes and also execute database dumps (like old script)",
+    )
+    p.add_argument(
+        "--shutdown",
+        action="store_true",
+        help="Do not restart containers after backup",
+    )
+    p.add_argument(
+        "--dump-only",
+        action="store_true",
+        help="Only create DB dumps (skip ALL file rsync backups)",
+    )
+
+    return p.parse_args()

src/baudolo/backup/compose.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import os
+import subprocess
+
+
+def hard_restart_docker_services(dir_path: str) -> None:
+    print(f"Hard restart docker-compose services in: {dir_path}", flush=True)
+    subprocess.run(["docker-compose", "down"], cwd=dir_path, check=True)
+    subprocess.run(["docker-compose", "up", "-d"], cwd=dir_path, check=True)
+
+
+def handle_docker_compose_services(parent_directory: str, hard_restart_required: list[str]) -> None:
+    for entry in os.scandir(parent_directory):
+        if not entry.is_dir():
+            continue
+
+        dir_path = entry.path
+        name = os.path.basename(dir_path)
+        compose_file = os.path.join(dir_path, "docker-compose.yml")
+
+        print(f"Checking directory: {dir_path}", flush=True)
+        if not os.path.isfile(compose_file):
+            print("No docker-compose.yml found. Skipping.", flush=True)
+            continue
+
+        if name in hard_restart_required:
+            print(f"{name}: hard restart required.", flush=True)
+            hard_restart_docker_services(dir_path)
+        else:
+            print(f"{name}: no restart required.", flush=True)

src/baudolo/backup/db.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+import os
+import pathlib
+import re
+
+import pandas
+
+from .shell import BackupException, execute_shell_command
+
+
+def get_instance(container: str, database_containers: list[str]) -> str:
+    if container in database_containers:
+        return container
+    return re.split(r"(_|-)(database|db|postgres)", container)[0]
+
+
+def fallback_pg_dumpall(container: str, username: str, password: str, out_file: str) -> None:
+    cmd = (
+        f"PGPASSWORD={password} docker exec -i {container} "
+        f"pg_dumpall -U {username} -h localhost > {out_file}"
+    )
+    execute_shell_command(cmd)
+
+
+def backup_database(
+    *,
+    container: str,
+    volume_dir: str,
+    db_type: str,
+    databases_df: "pandas.DataFrame",
+    database_containers: list[str],
+) -> None:
+    instance_name = get_instance(container, database_containers)
+    entries = databases_df.loc[databases_df["instance"] == instance_name]
+    if entries.empty:
+        raise BackupException(f"No entry found for instance '{instance_name}'")
+
+    out_dir = os.path.join(volume_dir, "sql")
+    pathlib.Path(out_dir).mkdir(parents=True, exist_ok=True)
+
+    for row in entries.iloc:
+        db_name = row["database"]
+        user = row["username"]
+        password = row["password"]
+
+        dump_file = os.path.join(out_dir, f"{db_name}.backup.sql")
+
+        if db_type == "mariadb":
+            cmd = (
+                f"docker exec {container} /usr/bin/mariadb-dump "
+                f"-u {user} -p{password} {db_name} > {dump_file}"
+            )
+            execute_shell_command(cmd)
+            continue
+
+        if db_type == "postgres":
+            cluster_file = os.path.join(out_dir, f"{instance_name}.cluster.backup.sql")
+            if not db_name:
+                fallback_pg_dumpall(container, user, password, cluster_file)
+                return
+
+            try:
+                cmd = (
+                    f"PGPASSWORD={password} docker exec -i {container} "
+                    f"pg_dump -U {user} -d {db_name} -h localhost > {dump_file}"
+                )
+                execute_shell_command(cmd)
+            except BackupException as e:
+                print(f"pg_dump failed: {e}", flush=True)
+                print(f"Falling back to pg_dumpall for instance '{instance_name}'", flush=True)
+                fallback_pg_dumpall(container, user, password, cluster_file)
+            continue

src/baudolo/backup/docker.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+from .shell import execute_shell_command
+
+
+def get_image_info(container: str) -> str:
+    return execute_shell_command(
+        f"docker inspect --format '{{{{.Config.Image}}}}' {container}"
+    )[0]
+
+
+def has_image(container: str, pattern: str) -> bool:
+    """Return True if container's image contains the pattern."""
+    return pattern in get_image_info(container)
+
+
+def docker_volume_names() -> list[str]:
+    return execute_shell_command("docker volume ls --format '{{.Name}}'")
+
+
+def containers_using_volume(volume_name: str) -> list[str]:
+    return execute_shell_command(
+        f"docker ps --filter volume=\"{volume_name}\" --format '{{{{.Names}}}}'"
+    )
+
+
+def change_containers_status(containers: list[str], status: str) -> None:
+    """Stop or start a list of containers."""
+    if not containers:
+        print(f"No containers to {status}.", flush=True)
+        return
+    names = " ".join(containers)
+    print(f"{status.capitalize()} containers: {names}...", flush=True)
+    execute_shell_command(f"docker {status} {names}")
+
+
+def docker_volume_exists(volume: str) -> bool:
+    # Avoid throwing exceptions for exists checks.
+    try:
+        execute_shell_command(f"docker volume inspect {volume} >/dev/null 2>&1 && echo OK")
+        return True
+    except Exception:
+        return False

src/baudolo/backup/shell.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import subprocess
+
+
+class BackupException(Exception):
+    """Generic exception for backup errors."""
+
+
+def execute_shell_command(command: str) -> list[str]:
+    """Execute a shell command and return its output lines."""
+    print(command, flush=True)
+    process = subprocess.Popen(
+        [command],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        shell=True,
+    )
+    out, err = process.communicate()
+    if process.returncode != 0:
+        raise BackupException(
+            f"Error in command: {command}\n"
+            f"Output: {out}\nError: {err}\n"
+            f"Exit code: {process.returncode}"
+        )
+    return [line.decode("utf-8") for line in out.splitlines()]

src/baudolo/backup/volume.py

@@ -0,0 +1,42 @@
+from __future__ import annotations
+
+import os
+import pathlib
+
+from .shell import BackupException, execute_shell_command
+
+
+def get_storage_path(volume_name: str) -> str:
+    path = execute_shell_command(
+        f"docker volume inspect --format '{{{{ .Mountpoint }}}}' {volume_name}"
+    )[0]
+    return f"{path}/"
+
+
+def get_last_backup_dir(versions_dir: str, volume_name: str, current_backup_dir: str) -> str | None:
+    versions = sorted(os.listdir(versions_dir), reverse=True)
+    for version in versions:
+        candidate = os.path.join(versions_dir, version, volume_name, "files", "")
+        if candidate != current_backup_dir and os.path.isdir(candidate):
+            return candidate
+    return None
+
+
+def backup_volume(versions_dir: str, volume_name: str, volume_dir: str) -> None:
+    """Perform incremental file backup of a Docker volume."""
+    dest = os.path.join(volume_dir, "files") + "/"
+    pathlib.Path(dest).mkdir(parents=True, exist_ok=True)
+
+    last = get_last_backup_dir(versions_dir, volume_name, dest)
+    link_dest = f"--link-dest='{last}'" if last else ""
+    source = get_storage_path(volume_name)
+
+    cmd = f"rsync -abP --delete --delete-excluded {link_dest} {source} {dest}"
+
+    try:
+        execute_shell_command(cmd)
+    except BackupException as e:
+        if "file has vanished" in str(e):
+            print("Warning: Some files vanished before transfer. Continuing.", flush=True)
+        else:
+            raise

src/baudolo/configure/__main__.py

@@ -0,0 +1,50 @@
+import pandas as pd
+import argparse
+import os
+
+def check_and_add_entry(file_path, instance, database, username, password):
+    # Check if the file exists and is not empty
+    if os.path.exists(file_path) and os.path.getsize(file_path) > 0:
+        # Read the existing CSV file with header
+        df = pd.read_csv(file_path, sep=';')
+    else:
+        # Create a new DataFrame with columns if file does not exist
+        df = pd.DataFrame(columns=['instance', 'database', 'username', 'password'])
+
+    # Check if the entry exists and remove it
+    mask = (
+        (df['instance'] == instance) &
+        ((df['database'] == database) |
+        (((df['database'].isna()) | (df['database'] == '')) & (database == ''))) &
+        (df['username'] == username)
+    )
+
+    if not df[mask].empty:
+        print("Replacing existing entry.")
+        df = df[~mask]
+    else:
+        print("Adding new entry.")
+
+    # Create a new DataFrame for the new entry
+    new_entry = pd.DataFrame([{'instance': instance, 'database': database, 'username': username, 'password': password}])
+
+    # Add (or replace) the entry using concat
+    df = pd.concat([df, new_entry], ignore_index=True)
+
+    # Save the updated CSV file
+    df.to_csv(file_path, sep=';', index=False)
+
+def main():
+    parser = argparse.ArgumentParser(description="Check and replace (or add) a database entry in a CSV file.")
+    parser.add_argument("file_path", help="Path to the CSV file")
+    parser.add_argument("instance", help="Database instance")
+    parser.add_argument("database", help="Database name")
+    parser.add_argument("username", help="Username")
+    parser.add_argument("password", nargs='?', default="", help="Password (optional)")
+
+    args = parser.parse_args()
+
+    check_and_add_entry(args.file_path, args.instance, args.database, args.username, args.password)
+
+if __name__ == "__main__":
+    main()

src/baudolo/restore/__init__.py

@@ -0,0 +1 @@
+__all__ = ["main"]

src/baudolo/restore/__main__.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from .paths import BackupPaths
+from .files import restore_volume_files
+from .db.postgres import restore_postgres_sql
+from .db.mariadb import restore_mariadb_sql
+
+
+def _add_common_backup_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument("volume_name", help="Docker volume name")
+    p.add_argument("backup_hash", help="Hashed machine id")
+    p.add_argument("version", help="Backup version directory name")
+
+    p.add_argument(
+        "--backups-dir",
+        default="/Backups",
+        help="Backup root directory (default: /Backups)",
+    )
+    p.add_argument(
+        "--repo-name",
+        default="backup-docker-to-local",
+        help="Backup repo folder name under <backups-dir>/<hash>/ (default: backup-docker-to-local)",
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="baudolo-restore",
+        description="Restore docker volume files and DB dumps.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_files = sub.add_parser("files", help="Restore files into a docker volume")
+    _add_common_backup_args(p_files)
+    p_files.add_argument("--rsync-image", default="ghcr.io/kevinveenbirkenbach/alpine-rsync")
+
+    p_pg = sub.add_parser("postgres", help="Restore a single PostgreSQL database dump")
+    _add_common_backup_args(p_pg)
+    p_pg.add_argument("--container", required=True)
+    p_pg.add_argument("--db-name", required=True)
+    p_pg.add_argument("--db-user", default=None, help="Defaults to db-name if omitted")
+    p_pg.add_argument("--db-password", required=True)
+    p_pg.add_argument("--empty", action="store_true")
+
+    p_mdb = sub.add_parser("mariadb", help="Restore a single MariaDB/MySQL-compatible dump")
+    _add_common_backup_args(p_mdb)
+    p_mdb.add_argument("--container", required=True)
+    p_mdb.add_argument("--db-name", required=True)
+    p_mdb.add_argument("--db-user", default=None, help="Defaults to db-name if omitted")
+    p_mdb.add_argument("--db-password", required=True)
+    p_mdb.add_argument("--empty", action="store_true")
+
+    args = parser.parse_args(argv)
+
+    bp = BackupPaths(
+        args.volume_name,
+        args.backup_hash,
+        args.version,
+        repo_name=args.repo_name,
+        backups_dir=args.backups_dir,
+    )
+
+    try:
+        if args.cmd == "files":
+            return restore_volume_files(args.volume_name, bp.files_dir(), rsync_image=args.rsync_image)
+
+        if args.cmd == "postgres":
+            user = args.db_user or args.db_name
+            restore_postgres_sql(
+                container=args.container,
+                db_name=args.db_name,
+                user=user,
+                password=args.db_password,
+                sql_path=bp.sql_file(args.db_name),
+                empty=args.empty,
+            )
+            return 0
+
+        if args.cmd == "mariadb":
+            user = args.db_user or args.db_name
+            restore_mariadb_sql(
+                container=args.container,
+                db_name=args.db_name,
+                user=user,
+                password=args.db_password,
+                sql_path=bp.sql_file(args.db_name),
+                empty=args.empty,
+            )
+            return 0
+
+        parser.error("Unhandled command")
+        return 2
+
+    except Exception as e:
+        print(f"ERROR: {e}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/baudolo/restore/db/__init__.py

@@ -0,0 +1 @@
+"""Database restore handlers (Postgres, MariaDB/MySQL)."""

src/baudolo/restore/db/mariadb.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+import sys
+
+from ..run import docker_exec, docker_exec_sh
+
+
+def _pick_client(container: str) -> str:
+    # Prefer mariadb, fallback to mysql (many images provide one or both).
+    script = r"""
+set -eu
+if command -v mariadb >/dev/null 2>&1; then echo mariadb; exit 0; fi
+if command -v mysql   >/dev/null 2>&1; then echo mysql;   exit 0; fi
+exit 42
+"""
+    try:
+        out = docker_exec_sh(container, script, capture=True).stdout.decode().strip()
+        if not out:
+            raise RuntimeError("empty client detection output")
+        return out
+    except Exception as e:
+        print("ERROR: neither 'mariadb' nor 'mysql' found in container.", file=sys.stderr)
+        raise e
+
+
+def restore_mariadb_sql(
+    *,
+    container: str,
+    db_name: str,
+    user: str,
+    password: str,
+    sql_path: str,
+    empty: bool,
+) -> None:
+    client = _pick_client(container)
+
+    if not os.path.isfile(sql_path):
+        raise FileNotFoundError(sql_path)
+
+    if empty:
+        # Close to old behavior: list tables, drop individually, then re-enable checks.
+        docker_exec(
+            container,
+            ["mysql", "-u", user, f"--password={password}", "-e", "SET FOREIGN_KEY_CHECKS=0;"],
+        )
+
+        result = docker_exec(
+            container,
+            [
+                "mysql",
+                "-u",
+                user,
+                f"--password={password}",
+                "-N",
+                "-e",
+                f"SELECT table_name FROM information_schema.tables WHERE table_schema = '{db_name}';",
+            ],
+            capture=True,
+        )
+        tables = result.stdout.decode().split()
+        for tbl in tables:
+            docker_exec(
+                container,
+                [
+                    "mysql",
+                    "-u",
+                    user,
+                    f"--password={password}",
+                    "-e",
+                    f"DROP TABLE IF EXISTS `{db_name}`.`{tbl}`;",
+                ],
+            )
+
+        docker_exec(
+            container,
+            ["mysql", "-u", user, f"--password={password}", "-e", "SET FOREIGN_KEY_CHECKS=1;"],
+        )
+
+    with open(sql_path, "rb") as f:
+        docker_exec(container, [client, "-u", user, f"--password={password}", db_name], stdin=f)
+
+    print(f"MariaDB/MySQL restore complete for db '{db_name}'.")

src/baudolo/restore/db/postgres.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+import os
+
+from ..run import docker_exec
+
+
+def restore_postgres_sql(
+    *,
+    container: str,
+    db_name: str,
+    user: str,
+    password: str,
+    sql_path: str,
+    empty: bool,
+) -> None:
+    if not os.path.isfile(sql_path):
+        raise FileNotFoundError(sql_path)
+
+    # Make password available INSIDE the container for psql.
+    docker_env = {"PGPASSWORD": password}
+
+    if empty:
+        drop_sql = r"""
+DO $$ DECLARE r RECORD;
+BEGIN
+  FOR r IN (
+    SELECT table_name AS name, 'TABLE' AS type FROM information_schema.tables WHERE table_schema='public'
+    UNION ALL
+    SELECT routine_name AS name, 'FUNCTION' AS type FROM information_schema.routines WHERE specific_schema='public'
+    UNION ALL
+    SELECT sequence_name AS name, 'SEQUENCE' AS type FROM information_schema.sequences WHERE sequence_schema='public'
+  ) LOOP
+    EXECUTE format('DROP %s public.%I CASCADE', r.type, r.name);
+  END LOOP;
+END $$;
+"""
+        docker_exec(
+            container,
+            ["psql", "-v", "ON_ERROR_STOP=1", "-U", user, "-d", db_name],
+            stdin=drop_sql.encode(),
+            docker_env=docker_env,
+        )
+
+    with open(sql_path, "rb") as f:
+        docker_exec(
+            container,
+            ["psql", "-v", "ON_ERROR_STOP=1", "-U", user, "-d", db_name],
+            stdin=f,
+            docker_env=docker_env,
+        )
+
+    print(f"PostgreSQL restore complete for db '{db_name}'.")

src/baudolo/restore/files.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import os
+import sys
+
+from .run import run, docker_volume_exists
+
+
+def restore_volume_files(volume_name: str, backup_files_dir: str, *, rsync_image: str) -> int:
+    if not os.path.isdir(backup_files_dir):
+        print(f"ERROR: backup files dir not found: {backup_files_dir}", file=sys.stderr)
+        return 2
+
+    if not docker_volume_exists(volume_name):
+        print(f"Volume {volume_name} does not exist. Creating...")
+        run(["docker", "volume", "create", volume_name])
+    else:
+        print(f"Volume {volume_name} already exists.")
+
+    # Keep behavior close to the old script: rsync -avv --delete
+    run(
+        [
+            "docker",
+            "run",
+            "--rm",
+            "-v",
+            f"{volume_name}:/recover/",
+            "-v",
+            f"{backup_files_dir}:/backup/",
+            rsync_image,
+            "sh",
+            "-lc",
+            "rsync -avv --delete /backup/ /recover/",
+        ]
+    )
+    print("File restore complete.")
+    return 0

src/baudolo/restore/paths.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class BackupPaths:
+    volume_name: str
+    backup_hash: str
+    version: str
+    repo_name: str
+    backups_dir: str = "/Backups"
+
+    def root(self) -> str:
+        # Always build an absolute path under backups_dir
+        return os.path.join(
+            self.backups_dir,
+            self.backup_hash,
+            self.repo_name,
+            self.version,
+            self.volume_name,
+        )
+
+    def files_dir(self) -> str:
+        return os.path.join(self.root(), "files")
+
+    def sql_file(self, db_name: str) -> str:
+        return os.path.join(self.root(), "sql", f"{db_name}.backup.sql")

src/baudolo/restore/run.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+import subprocess
+import sys
+from typing import Optional
+
+
+def run(
+    cmd: list[str],
+    *,
+    stdin=None,
+    capture: bool = False,
+    env: Optional[dict] = None,
+) -> subprocess.CompletedProcess:
+    try:
+        return subprocess.run(
+            cmd,
+            check=True,
+            stdin=stdin,
+            capture_output=capture,
+            env=env,
+        )
+    except subprocess.CalledProcessError as e:
+        msg = f"ERROR: command failed ({e.returncode}): {' '.join(cmd)}"
+        print(msg, file=sys.stderr)
+        if e.stdout:
+            try:
+                print(e.stdout.decode(), file=sys.stderr)
+            except Exception:
+                print(e.stdout, file=sys.stderr)
+        if e.stderr:
+            try:
+                print(e.stderr.decode(), file=sys.stderr)
+            except Exception:
+                print(e.stderr, file=sys.stderr)
+        raise
+
+
+def docker_exec(
+    container: str,
+    argv: list[str],
+    *,
+    stdin=None,
+    capture: bool = False,
+    env: Optional[dict] = None,
+    docker_env: Optional[dict[str, str]] = None,
+) -> subprocess.CompletedProcess:
+    cmd: list[str] = ["docker", "exec", "-i"]
+    if docker_env:
+        for k, v in docker_env.items():
+            cmd.extend(["-e", f"{k}={v}"])
+    cmd.extend([container, *argv])
+    return run(cmd, stdin=stdin, capture=capture, env=env)
+
+
+def docker_exec_sh(
+    container: str,
+    script: str,
+    *,
+    stdin=None,
+    capture: bool = False,
+    env: Optional[dict] = None,
+    docker_env: Optional[dict[str, str]] = None,
+) -> subprocess.CompletedProcess:
+    return docker_exec(
+        container,
+        ["sh", "-lc", script],
+        stdin=stdin,
+        capture=capture,
+        env=env,
+        docker_env=docker_env,
+    )
+
+
+def docker_volume_exists(volume: str) -> bool:
+    p = subprocess.run(
+        ["docker", "volume", "inspect", volume],
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+    )
+    return p.returncode == 0