vbart 0.1.0__tar.gz

vbart-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright 2024 Peter Nardi
+
+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:
+
+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 NON-INFRINGEMENT.
+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.

vbart-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.1
+Name: vbart
+Version: 0.1.0
+Summary: Volume Backup And Restoration Tool for Docker
+Home-page: https://github.com/geozeke/vbart
+Keywords: archive,backup,compose,compress,compression,docker,restore,vbart,volume,volumes
+Author: Peter Nardi
+Author-email: pete@nardi.com
+Maintainer: Peter Nardi
+Maintainer-email: pete@nardi.com
+Requires-Python: >=3.8.1,<4.0.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Topic :: System :: Archiving :: Backup
+Classifier: Topic :: System :: Archiving :: Compression
+Classifier: Topic :: Utilities
+Requires-Dist: docker (>=7.0.0,<8.0.0)
+Project-URL: Bug Tracker, https://github.com/geozeke/vbart/issues
+Project-URL: Source Code, https://github.com/geozeke/vbart
+Description-Content-Type: text/markdown
+
+# vbart
+
+![GitHub](https://img.shields.io/github/license/geozeke/vbart)
+![PyPI](https://img.shields.io/pypi/v/vbart)
+![PyPI - Status](https://img.shields.io/pypi/status/vbart)
+![GitHub last commit](https://img.shields.io/github/last-commit/geozeke/vbart)
+![GitHub issues](https://img.shields.io/github/issues/geozeke/vbart)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/parser201)
+![GitHub repo size](https://img.shields.io/github/repo-size/geozeke/vbart)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vbart)
+
+<br>
+
+<img
+src="https://drive.google.com/uc?export=view&id=1H04KVAA3ohH_dLXIrC0bXuJXDn3VutKc"
+alt = "Dinobox logo" width="120"/>
+
+## Volume Backup And Restoration Tool for Docker
+
+Why is backing up named docker volumes so hard? There's an
+[extension][def] for Docker Desktop, but I just want a simple, easy to
+use, command-line tool that allows me to backup and restore my named
+docker volumes. That's what vbart does.
+
+With vbart you can:
+
+* Backup a single named volume.
+* Backup all active named volumes on your host.
+* Backup just the volumes you list in a separate file.
+* Restore a single backup to a named volume.
+
+All backups are stored in compressed (xz) tar archives. Once you create
+a backup, you can copy it off-host, install it on another machine, share
+with friends, etc.
+
+### Installation
+
+The preferred way to install vbart is with [pipx][def2]:
+
+```shell
+pipx install vbart
+```
+
+Alternatively, you can create a separate virtual environment and install
+it the traditional way:
+
+```shell
+pip3 install vbart
+```
+
+### Usage
+
+For an overview, run:
+
+```shell
+vbart -h
+```
+
+### Backup a Single Volume
+
+```shell
+vbart backup volume_name
+```
+
+For example, to backup a volume named `mysql_db`, use:
+
+```shell
+vbart backup mysql_db
+```
+
+vbart will then create a backup file in your current working directory
+named:
+
+```text
+YYYYMMDD-mysql_db-backup.xz
+```
+
+### Backup Multiple Volumes
+
+```shell
+vbart backups [-v VOLUMES]
+```
+
+Note the plural command name (`backups` as opposed to `backup`).
+`VOLUMES` is the optional name of a textfile that contains case
+sensitive volume names (one per line) that you want to backup. Within
+`VOLUMES` blank lines and lines beginning with `#` are ignored, so you
+can comment the file if you wish.
+
+If `VOLUMES` is not specified, all active docker volumes on the current
+host are backed up. All volume backups are saved in the current working
+directory and named as:
+
+```text
+YYYYMMDD-{volume_name}-backup.xz
+```
+
+### Restore a Single Volume
+
+```shell
+vbart restore backup_file volume_name
+```
+
+The first argument (`backup_file`) is the compressed tar archive you
+created when you made a backup. The file must have a `.xz` extension.
+
+The second argument (`volume_name`) is the named volume to create from
+the backup. If the named volume already exists, vbart will terminate
+with no action. Otherwise, a new empty volume will be created with the
+given name and the backup will be restored to that volume.
+
+### Refresh vbart
+
+If vbart is interrupted during execution (e.g. hitting `Control+C`),
+then there may be dangling docker containers that hang on to existing
+volumes. Running the refresh command will clear those dangling
+containers.
+
+Also, when you run vbart for the first time, it creates a small
+(alpine-based) docker image to perform the actual backups. This image is
+called `vbart_utility`. The refresh command also deletes the utility
+image, causing it to be recreated the next time you run vbart.
+
+To refresh vbart, use:
+
+```shell
+vbart refresh
+```
+
+[def]: https://hub.docker.com/extensions/docker/volumes-backup-extension
+[def2]: https://pipx.pypa.io/stable/
+

vbart-0.1.0/README.md

@@ -0,0 +1,131 @@
+# vbart
+
+![GitHub](https://img.shields.io/github/license/geozeke/vbart)
+![PyPI](https://img.shields.io/pypi/v/vbart)
+![PyPI - Status](https://img.shields.io/pypi/status/vbart)
+![GitHub last commit](https://img.shields.io/github/last-commit/geozeke/vbart)
+![GitHub issues](https://img.shields.io/github/issues/geozeke/vbart)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/parser201)
+![GitHub repo size](https://img.shields.io/github/repo-size/geozeke/vbart)
+![PyPI - Python Version](https://img.shields.io/pypi/pyversions/vbart)
+
+<br>
+
+<img
+src="https://drive.google.com/uc?export=view&id=1H04KVAA3ohH_dLXIrC0bXuJXDn3VutKc"
+alt = "Dinobox logo" width="120"/>
+
+## Volume Backup And Restoration Tool for Docker
+
+Why is backing up named docker volumes so hard? There's an
+[extension][def] for Docker Desktop, but I just want a simple, easy to
+use, command-line tool that allows me to backup and restore my named
+docker volumes. That's what vbart does.
+
+With vbart you can:
+
+* Backup a single named volume.
+* Backup all active named volumes on your host.
+* Backup just the volumes you list in a separate file.
+* Restore a single backup to a named volume.
+
+All backups are stored in compressed (xz) tar archives. Once you create
+a backup, you can copy it off-host, install it on another machine, share
+with friends, etc.
+
+### Installation
+
+The preferred way to install vbart is with [pipx][def2]:
+
+```shell
+pipx install vbart
+```
+
+Alternatively, you can create a separate virtual environment and install
+it the traditional way:
+
+```shell
+pip3 install vbart
+```
+
+### Usage
+
+For an overview, run:
+
+```shell
+vbart -h
+```
+
+### Backup a Single Volume
+
+```shell
+vbart backup volume_name
+```
+
+For example, to backup a volume named `mysql_db`, use:
+
+```shell
+vbart backup mysql_db
+```
+
+vbart will then create a backup file in your current working directory
+named:
+
+```text
+YYYYMMDD-mysql_db-backup.xz
+```
+
+### Backup Multiple Volumes
+
+```shell
+vbart backups [-v VOLUMES]
+```
+
+Note the plural command name (`backups` as opposed to `backup`).
+`VOLUMES` is the optional name of a textfile that contains case
+sensitive volume names (one per line) that you want to backup. Within
+`VOLUMES` blank lines and lines beginning with `#` are ignored, so you
+can comment the file if you wish.
+
+If `VOLUMES` is not specified, all active docker volumes on the current
+host are backed up. All volume backups are saved in the current working
+directory and named as:
+
+```text
+YYYYMMDD-{volume_name}-backup.xz
+```
+
+### Restore a Single Volume
+
+```shell
+vbart restore backup_file volume_name
+```
+
+The first argument (`backup_file`) is the compressed tar archive you
+created when you made a backup. The file must have a `.xz` extension.
+
+The second argument (`volume_name`) is the named volume to create from
+the backup. If the named volume already exists, vbart will terminate
+with no action. Otherwise, a new empty volume will be created with the
+given name and the backup will be restored to that volume.
+
+### Refresh vbart
+
+If vbart is interrupted during execution (e.g. hitting `Control+C`),
+then there may be dangling docker containers that hang on to existing
+volumes. Running the refresh command will clear those dangling
+containers.
+
+Also, when you run vbart for the first time, it creates a small
+(alpine-based) docker image to perform the actual backups. This image is
+called `vbart_utility`. The refresh command also deletes the utility
+image, causing it to be recreated the next time you run vbart.
+
+To refresh vbart, use:
+
+```shell
+vbart refresh
+```
+
+[def]: https://hub.docker.com/extensions/docker/volumes-backup-extension
+[def2]: https://pipx.pypa.io/stable/

vbart-0.1.0/pyproject.toml

@@ -0,0 +1,61 @@
+[tool.poetry]
+name = "vbart"
+version = "0.1.0"
+description = "Volume Backup And Restoration Tool for Docker"
+authors = ["Peter Nardi <pete@nardi.com>"]
+maintainers = ["Peter Nardi <pete@nardi.com>"]
+homepage = "https://github.com/geozeke/vbart"
+readme = "README.md"
+packages = [{ include = "vbart", from = "src" }]
+include = ["LICENSE"]
+keywords = [
+    "archive",
+    "backup",
+    "compose",
+    "compress",
+    "compression",
+    "docker",
+    "restore",
+    "vbart",
+    "volume",
+    "volumes",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "Intended Audience :: System Administrators",
+    "License :: OSI Approved :: MIT License",
+    "Natural Language :: English",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: System :: Archiving :: Backup",
+    "Topic :: System :: Archiving :: Compression",
+    "Topic :: Utilities",
+]
+
+[tool.poetry.urls]
+"Source Code" = "https://github.com/geozeke/vbart"
+"Bug Tracker" = "https://github.com/geozeke/vbart/issues"
+
+[tool.poetry.scripts]
+vbart = "vbart.__main__:main"
+
+[tool.poetry.dependencies]
+python = "^3.8.1"
+docker = "^7.0.0"
+
+[tool.poetry.group.dev.dependencies]
+flake8 = "^7.0.0"
+flake8-docstrings = "^1.7.0"
+mypy = "^1.9.0"
+black = "^24.3.0"
+isort = "^5.13.2"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

vbart-0.1.0/src/vbart/Dockerfile

@@ -0,0 +1,4 @@
+FROM alpine:latest
+RUN apk -U upgrade
+# Add support for xz compression
+RUN apk add --no-cache xz

vbart-0.1.0/src/vbart/__main__.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+
+"""Entry point for vbart."""
+
+import argparse
+import importlib
+import shutil
+import sys
+from pathlib import Path
+from types import ModuleType
+from typing import List
+from typing import Union
+
+from vbart.constants import ARG_PARSERS_BASE
+
+# ======================================================================
+
+
+def collect_modules(start: Path) -> List[str]:
+    """Collect the names of all modules to import.
+
+    Parameters
+    ----------
+    start : Path
+        This the starting point (directory) for collection.
+
+    Returns
+    -------
+    list[str]
+        A list of module names.
+    """
+    mod_names: List[str] = []
+    for p in start.iterdir():
+        if p.is_file() and p.name != "__init__.py":
+            if "plugins" in str(p):
+                prefix = "plugins.parsers"
+            else:
+                prefix = "parsers"
+            mod_names.append(f"{prefix}.{p.stem}")
+    return mod_names
+
+
+# ======================================================================
+
+
+def main() -> None:
+    """Get user input and perform backup and restore operations."""
+    # Make sure docker is installed before going any further
+    if not (shutil.which("docker")):
+        print("\nYou must have docker installed to use vbart.\n")
+        sys.exit(1)
+
+    msg = """Volume Backup And Restoration Tool (for docker). A tool to
+    easily backup and restore named docker volumes. For help on any
+    command below, use: vbart {command} -h"""
+    epi = "Version: 0.1.0"
+    parser = argparse.ArgumentParser(
+        description=msg,
+        epilog=epi,
+    )
+    subparsers = parser.add_subparsers(title="commands", dest="cmd")
+
+    # Dynamically load argument subparsers.
+
+    mod_names: List[str] = []
+    mod: Union[ModuleType, None] = None
+    mod_names = collect_modules(ARG_PARSERS_BASE)
+    mod_names.sort()
+
+    # Argument parsers are saved in alphabetical order. This is a little
+    # slight-of-hand to get the desired order presented on screen.
+    mod_names[-1], mod_names[-2] = mod_names[-2], mod_names[-1]
+
+    for mod_name in mod_names:
+        mod = importlib.import_module(mod_name)
+        mod.load_command_args(subparsers)
+
+    args = parser.parse_args()
+    if args.cmd == "backup":
+        mod = importlib.import_module("vbart.backup")
+    elif args.cmd == "backups":
+        mod = importlib.import_module("vbart.backups")
+    elif args.cmd == "restore":
+        mod = importlib.import_module("vbart.restore")
+    elif args.cmd == "refresh":
+        mod = importlib.import_module("vbart.refresh")
+    else:
+        mod = importlib.import_module("vbart.null")
+    mod.task_runner(args)
+
+    return
+
+
+if __name__ == "__main__":
+    main()

vbart-0.1.0/src/vbart/backup.py

@@ -0,0 +1,42 @@
+"""Perform single volume backup."""
+
+import argparse
+import sys
+
+import docker  # type:ignore
+from docker import errors
+
+from vbart.classes import Labels
+from vbart.utilities import backup_one_volume
+from vbart.utilities import clear
+from vbart.utilities import verify_utility_image
+
+
+def task_runner(args: argparse.Namespace) -> None:
+    """Backup a single named docker volume.
+
+    Parameters
+    ----------
+    args : Namespace
+        Command line arguments.
+    """
+    verify_utility_image()
+    client = docker.from_env()
+
+    try:
+        client.volumes.get(args.volume_name)
+        msg = f'Backing up volume "{args.volume_name}"'
+        labels = Labels(msg)
+    except errors.NotFound:
+        print(f'Volume "{args.volume_name}" not found.')
+        sys.exit(1)
+
+    clear()
+    labels.next()
+    print(backup_one_volume(args.volume_name))
+
+    return
+
+
+if __name__ == "__main__":
+    pass

vbart-0.1.0/src/vbart/backups.py

@@ -0,0 +1,60 @@
+"""Perform backup of multiple volumes."""
+
+import argparse
+
+import docker  # type:ignore
+
+from vbart.classes import Labels
+from vbart.utilities import backup_one_volume
+from vbart.utilities import clear
+from vbart.utilities import verify_utility_image
+from vbart.utilities import wrap_tight
+
+
+def task_runner(args: argparse.Namespace) -> None:
+    """Backup multiple docker volumes.
+
+    Parameters
+    ----------
+    args : Namespace
+        Command line arguments.
+    """
+    verify_utility_image()
+    clear()
+    client = docker.from_env()
+    active_names = [v.name for v in client.volumes.list()]  # type:ignore
+
+    if args.volumes:
+        print(f"Performing backups using {args.volumes.name}\n")
+        custom_names = [
+            t for
+            token in args.volumes
+            if (t := token.strip()) and (t[0] != "#")
+        ]  # fmt: skip
+        args.volumes.close()
+        target_names = list(set(active_names).intersection(set(custom_names)))
+    else:
+        print("Backing up all active docker volumes\n")
+        target_names = active_names.copy()
+    target_names.sort()
+
+    if target_names:
+        label_list = [f'Backing up volume "{name}"' for name in target_names]
+        labels = Labels("\n".join(label_list))
+        for name in target_names:
+            labels.next()
+            print(backup_one_volume(name))
+    else:
+        if args.volumes:
+            msg = f"""None of the volume names listed in
+            {args.volumes.name} are currently showing up as active
+            docker volumes."""
+            print(wrap_tight(msg=msg, columns=60))
+        else:
+            print("No active docker volumes found.")
+
+    return
+
+
+if __name__ == "__main__":
+    pass

vbart-0.1.0/src/vbart/classes.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Support classes."""
+
+import sys
+
+
+class ExhaustedListError(Exception):
+    """Exception when attempting to pop elements from an empty list.
+
+    Parameters
+    ----------
+    Exception : Python Exception type
+        ExhaustedListError is a sub-class of Python's Exception class.
+    """
+
+    def __init__(self):
+        """Initialize exception."""
+        self.message = "Cannot remove label, list of labels is empty."
+        super().__init__(self.message)
+
+
+class Labels:
+    """Class to manage status labels."""
+
+    def __init__(self, s: str) -> None:
+        """Create a new Labels object.
+
+        Parameters
+        ----------
+        s : str
+            This is a docstring that has one label per line, the
+            initializer will repackage it into a list, along with an int
+            variable (pad) that represents the length of the longest
+            label. This is used for justifying the output when printing.
+        """
+        # The (t := token.strip()) part of the list comprehension below is
+        # python's assignment expression and takes care of any blank lines or
+        # leading/trailing whitespace in the docstring. It assigns
+        # token.strip() to t then evaluates t. If t is an empty string, it
+        # evaluates to False otherwise it's True.
+        self.labels = [t for token in s.split("\n") if (t := token.strip())]
+        self.pad = len(max(self.labels, key=len)) + 3
+        return
+
+    def next(self) -> None:
+        """Print the next label (the one at position 0).
+
+        Raises
+        ------
+        ExhaustedListError
+            If attempting to pop from an empty list.
+        """
+        if len(self.labels) == 0:
+            raise ExhaustedListError()
+        print(f"{self.labels.pop(0):.<{self.pad}}", end="", flush=True)
+        return
+
+    def pop_first(self) -> str:
+        """Pop and return the first label (position 0).
+
+        Returns
+        -------
+        str
+            A label.
+
+        Raises
+        ------
+        ExhaustedListError
+            If attempting to pop from an empty list.
+        """
+        if len(self.labels) == 0:
+            raise ExhaustedListError()
+        return self.labels.pop(0)
+
+    def pop_last(self) -> str:
+        """Pop and return the last label (position -1).
+
+        Returns
+        -------
+        str
+            A label.
+
+        Raises
+        ------
+        ExhaustedListError
+            If attempting to pop from an empty list.
+        """
+        if len(self.labels) == 0:
+            raise ExhaustedListError()
+        return self.labels.pop(-1)
+
+    def pop_item(self, index: int) -> str:
+        """Pop a label from a given index.
+
+        Parameters
+        ----------
+        index : int
+            The index to pop from.
+
+        Returns
+        -------
+        str
+            The popped label.
+
+        Raises
+        ------
+        ExhaustedListError
+            If attempting to pop from an empty list.
+        """
+        if len(self.labels) == 0:
+            raise ExhaustedListError()
+        try:
+            label = self.labels.pop(index)
+            return label
+        except IndexError as e:
+            print(f"{e}. Attempting to pop index {index}.")
+            print("Terminating program.")
+            sys.exit(1)
+
+
+if __name__ == "__main__":
+    pass

vbart-0.1.0/src/vbart/constants.py

@@ -0,0 +1,17 @@
+"""Constants."""
+
+from pathlib import Path
+
+GREEN = "\033[0;32;49m"
+RED = "\033[0;31;49m"
+COLOR_END = "\x1b[0m"
+
+PASS = f"{GREEN}\u2714{COLOR_END}"
+FAIL = f"{RED}\u2718{COLOR_END}"
+
+HOME = Path(__file__).parents[2]
+
+ARG_PARSERS_BASE = HOME / "src/parsers"
+BASE_IMAGE = "alpine:latest"
+DOCKERFILE_PATH = HOME / "src/vbart"
+UTILITY_IMAGE = "vbart_utility"

vbart-0.1.0/src/vbart/null.py

@@ -0,0 +1,13 @@
+"""Taskrunner for no command.
+
+This will be the default command, which reminds the user how to use the
+program, then exits.
+"""
+
+import argparse
+
+
+def task_runner(args: argparse.Namespace) -> None:
+    """Print reminder message and exit."""
+    print("run 'vbart -h' for help.")
+    return

vbart-0.1.0/src/vbart/refresh.py

@@ -0,0 +1,55 @@
+"""Remove the vbart_utility image."""
+
+import argparse
+
+import docker  # type:ignore
+from docker import errors
+
+from vbart.constants import UTILITY_IMAGE
+
+
+def task_runner(args: argparse.Namespace) -> None:
+    """Purge any dangling containers and remove the vbart_utility image.
+
+    If a backup is interrupted (e.g. cntl-C), then there may be dangling
+    containers that are still hanging on to existing volumes. The
+    refresh option purges those dangling containers.
+
+    Parameters
+    ----------
+    args : Namespace
+        Command line arguments.
+    """
+    client = docker.from_env()
+
+    # Prune any dangling containers.
+
+    filter = {"ancestor": f"{UTILITY_IMAGE}:latest"}
+    dangling = client.containers.list(
+        all=True,
+        filters=filter,
+    )
+
+    for container in dangling:
+        container.remove(force=True)  # type:ignore
+
+    # Delete the utility image and appropriate dependency.
+
+    try:
+        client.images.get(UTILITY_IMAGE)
+        client.images.remove(UTILITY_IMAGE)
+    except errors.NotFound:
+        print("No refresh needed. All good.")
+        return
+
+    if dangling:
+        noun = "container" if len(dangling) == 1 else "containers"
+        print(f"{len(dangling)} dangling {noun} removed.")
+    print(f"The {UTILITY_IMAGE} image was deleted.")
+    print(f"{UTILITY_IMAGE} will be recreated the next time you run vbart.")
+
+    return
+
+
+if __name__ == "__main__":
+    pass

vbart-0.1.0/src/vbart/restore.py

@@ -0,0 +1,79 @@
+"""Perform volume restoration."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import docker  # type:ignore
+from docker import errors
+
+from vbart.classes import Labels
+from vbart.constants import FAIL
+from vbart.constants import PASS
+from vbart.constants import UTILITY_IMAGE
+from vbart.utilities import clear
+from vbart.utilities import verify_utility_image
+
+
+def task_runner(args: argparse.Namespace) -> None:
+    """Restore a backup to a docker volume.
+
+    Parameters
+    ----------
+    args : Namespace
+        Command line arguments.
+    """
+    verify_utility_image()
+    client = docker.from_env()
+
+    # Check to see if the volume already exists. If so, report that and
+    # exit. If it doesn't exist, create it. Also, close the backup file
+    # - when it comes time to run the container, we only need the name.
+
+    args.backup_file.close()
+    try:
+        client.volumes.get(args.volume_name)
+        print(f'Volume "{args.volume_name}" already exists.')
+        print("No restoration performed.")
+        sys.exit(0)
+    except errors.NotFound:
+        msg = f'Restoring backup to volume "{args.volume_name}"'
+        volume = client.volumes.create(args.volume_name)
+        labels = Labels(msg)
+
+    # Build volume map.
+
+    p = Path(args.backup_file.name)
+    volume_map = {
+        args.volume_name: {"bind": "/recover", "mode": "rw"},
+        p.parent.absolute(): {"bind": "/backup", "mode": "rw"},
+    }
+
+    # Build the shell command to be run in the container
+
+    shell_arg = f'"cd /recover && tar xvf /backup/{p.name} --strip 1"'
+    shell_cmd = f"sh -c {shell_arg}"
+
+    # Run the container and extract the backup.
+
+    try:
+        clear()
+        labels.next()
+        client.containers.run(
+            image=UTILITY_IMAGE,
+            command=shell_cmd,
+            remove=True,
+            volumes=volume_map,
+        )
+        print(PASS)
+    except errors.ContainerError:
+        print(FAIL)
+        print("\nInvalid backup file provided. Unable to restore.")
+        volume.remove()  # type:ignore
+        sys.exit(1)
+
+    return
+
+
+if __name__ == "__main__":
+    pass

vbart-0.1.0/src/vbart/utilities.py

@@ -0,0 +1,145 @@
+"""Utilities to support docker volume backup/restore."""
+
+import os
+import tempfile as tf
+import textwrap
+from datetime import datetime as dt
+from pathlib import Path
+
+import docker  # type:ignore
+from docker import errors
+
+from vbart.constants import BASE_IMAGE
+from vbart.constants import DOCKERFILE_PATH
+from vbart.constants import FAIL
+from vbart.constants import PASS
+from vbart.constants import UTILITY_IMAGE
+
+# ======================================================================
+
+
+def wrap_tight(msg: str, columns=70) -> str:
+    """Clean up a multi-line docstring.
+
+    Take a multi-line docstring and wrap it cleanly as a paragraph to a
+    specified column width.
+
+    Parameters
+    ----------
+    msg : str
+        The docstring to be wrapped.
+    columns : int, optional
+        Column width for wrapping, by default 70.
+
+    Returns
+    -------
+    str
+        A wrapped paragraph.
+    """
+    clean = " ".join([t for token in msg.split("\n") if (t := token.strip())])
+    return textwrap.fill(clean, width=columns)
+
+
+# ======================================================================
+
+
+def clear() -> None:
+    """Clear the screen.
+
+    OS-agnostic version, which will work with both Windows and Linux.
+    """
+    os.system("clear" if os.name == "posix" else "cls")
+
+
+# ======================================================================
+
+
+def verify_utility_image() -> None:
+    """Verify the backup utility image is in place.
+
+    If the utility image is not present, then build it. Also delete any
+    interim build products (images) that were created.
+    """
+    # NOTE: The python docker package is not typed, so you'll see lots
+    # of "type: ignore" hashtags sprinkled throughout.
+
+    client = docker.from_env()
+    try:
+        client.images.get(UTILITY_IMAGE)
+        return
+    except errors.ImageNotFound:
+        pass
+
+    # If the alpine image is already installed, don't delete it after
+    # creating the utility image.
+
+    try:
+        client.images.get(BASE_IMAGE)
+        alpine_present = True
+    except errors.ImageNotFound:
+        alpine_present = False
+
+    msg = "Building utility image (this is a one-time operation)..."
+    print(f"{msg}", end="", flush=True)
+    client.images.build(
+        path=str(DOCKERFILE_PATH),
+        tag=f"{UTILITY_IMAGE}:latest",
+        nocache=True,
+        rm=True,
+    )
+
+    # Saving and reloading the image flattens it so it will operate
+    # standalone, meaning it won't need any parent image dependencies.
+
+    utility_image = client.images.get(UTILITY_IMAGE)
+    with tf.TemporaryFile() as f:
+        for chunk in utility_image.save(named=True):  # type: ignore
+            f.write(chunk)
+        f.seek(0)
+        client.images.remove(UTILITY_IMAGE)
+        if not alpine_present:
+            client.images.remove(BASE_IMAGE)
+        client.images.load(f)
+
+    return
+
+
+# ======================================================================
+
+
+def backup_one_volume(volume: str) -> str:
+    """Perform a backup on a single named volume.
+
+    Parameters
+    ----------
+    volume : str
+        The name of the volume to backup
+
+    Returns
+    -------
+    str
+        Return either PASS or FAIL, depending on the result of the
+        backup.
+    """
+    client = docker.from_env()
+    now = dt.now()
+    prefix = f"{now.year}{now.month:02d}{now.day:02d}"
+    p = Path(f"{prefix}-{volume}-backup.xz")
+    volume_map = {
+        volume: {"bind": "/recover", "mode": "rw"},
+        p.parent.absolute(): {"bind": "/backup", "mode": "rw"},
+    }
+    cmd = f"tar cavf /backup/{p.name} /recover"
+
+    # Run the container and perform the backup.
+
+    try:
+        client.containers.run(
+            image=UTILITY_IMAGE,
+            command=cmd,
+            remove=True,
+            volumes=volume_map,
+        )
+        return PASS
+    except errors.ContainerError:
+        return FAIL