kistn 0.1.0__tar.gz

kistn-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.3
+Name: kistn
+Version: 0.1.0
+Summary: A lightweight backup solution using BorgBackup and a Hetzner storage box.
+Author: Kangonaut
+Author-email: Kangonaut <120662571+Kangonaut@users.noreply.github.com>
+Requires-Dist: packaging>=26.3
+Requires-Dist: platformdirs>=4.11.3
+Requires-Dist: pydantic>=2.13.4
+Requires-Dist: pyyaml>=6.0.3
+Requires-Dist: questionary>=2.1.1
+Requires-Dist: rich>=15.0.0
+Requires-Dist: typer>=0.27.1
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# 📦 `kistn`
+
+[![license](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://github.com/Kangonaut/kistn/blob/main/LICENSE)
+
+</div>
+
+`kistn` is lightweight backup solution using [BorgBackup](https://www.borgbackup.org/), [Borgmatic](https://torsion.org/borgmatic/) and a [Hetzner storage box](https://www.hetzner.com/storage/storage-box/).
+
+### Why does this project exist?
+
+I am very forgetful. I've been using Borgmatic to run my backups for a while now, but every time I want to configure a new backup, I need to look up how to do it again. Sure, I could simply write a guide for myself or ask some AI, but I thought: Why not create a small CLI tool that does everything for me. This also solves my second problem: I always forget to actually do the backups. So why not build a tool that guides you through the setup and also reminds you to do your backups, or even does the backups automatically in the background.
+
+### Should I use `kistn`?
+
+If you are also forgetful or you don't want to read up on how Borgmatic works, then I think this might be a helpful tool for you. I've tried to make the user experience as simple as possible and to guide the user through the setup process. I hope that this means that it can even be used by people, who are not heavy-terminal users. However, it is a CLI tool, so if you'd rather just click some buttons in a fancy GUI, there are surely better options out there. Anyway, this tool is far from being a mature software, but I think it is still usable. If you encounter any problems, you can open an issue and hope for a reply. Sorry, I'm often busy. :)
+
+### Why should I use a Hetzner storage backup box?
+
+There are many other options out there and I'm not saying Hetzner has the best solution. But considering the options I've used so far, it is probably the best and cheapest option I know. `kistn` technically works with any server that is running `borg` and OpenSSH, but it is meant to be used with a Hetzner storage box, because that's what I use. :)
+
+## Getting Started
+
+### 0. Install `uv`
+
+`uv` is a really nice Python package manager. It's technically not required to install `kistn`, but if you don't know what you are doing, simply use `uv`. You won't be disappointed.
+
+1. Check if `uv` is already installed: `uv --version`.
+2. If not, follow the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/) or simply run the following command:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 1. Install `kistn`
+
+1. Install using `uv`: `uv tool install kistn`
+
+### 2. Check Dependencies
+
+1. Run `kistn doctor` to see if your system has all the necessary packages installed.
+
+### 3. (Optional) Add Overdue-Check to Shell Config
+
+If you want to get a reminder to do your overdue backups every time you open a new shell session, then follow the instructions below. The reminder will look something like this:
+
+```shell
+⚠ WARN: basic: Your last backup was 7 days ago. Run `kistn run basic` to start the backup.
+```
+
+1. Open your shell config in your favourite editor. If you are using `zsh`, open `~/.zshrc`. If you are using `bash`, open `.bashrc`.
+2. If you're using `bash` or `zsh`, add the following lines to the very top of your config:
+
+```bash
+# Check for overdue kistn backups
+if [ -f "$HOME/.local/bin/kistn" ]; then
+    "$HOME/.local/bin/kistn" check-overdue
+fi
+```
+
+TODO: add instructions for other shells like `fish`
+
+### 4. Setup the Storage Box
+
+1. Go to the [Hetzner Console](https://console.hetzner.com/) and find your storage box.
+2. Make sure that **SSH Support** and **External Reachability** is enabled.
+3. Keep the page open to look up the hostname, username and port later.
+
+### 5. Create a Remote Connection
+
+1. Run `kistn remote wizard NAME` and follow the instructions. `NAME` should be a simple name to identify your storage box. It probably makes sense to simply adopt the name that is displayed in the Hetzner Console.
+2. Run `kistn remote list` to check if the remote connection is ready to use. It should say `ready` in the `State` column.
+
+**NOTE:** If the `kistn remote wizard` command fails or you interrupt it, you can continue the setup by simply running the command again.
+
+<div align="center">
+    <img src="assets/remote-wizard.png" width="640"/>
+</div>
+
+### 6. Create a Backup Profile
+
+1. Run `kistn profile wizard NAME` and follow the instructions. `NAME` should again be a simple name to identify your backup profile, such as `basic`, `documents`, `university`, `photos`, ...
+2. Make sure you store your paper key at a secure location.
+3. Run `kistn profile list` to check if the profile is ready. Again, it should say `ready` in the `State` column.
+
+**NOTE:** If the `kistn remote profile` command fails or you interrupt it, you can continue the setup by simply running the command again.
+
+<div align="center">
+    <img src="assets/profile-wizard.png" width="640"/>
+</div>
+
+### 7. Create your first Backup
+
+1. Run your first backup using `kistn run PROFILE-NAME`.
+
+### 8. Check when to do your next Backup
+
+1. Use `kistn status` to see when you did your last backup and when the next backup is due. If you chose a frequency of 7, it should say `in 7 days`.
+
+## License
+
+Distributed under the [Apache License 2.0](https://github.com/Kangonaut/kistn/blob/main/LICENSE).

kistn-0.1.0/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+
+# 📦 `kistn`
+
+[![license](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://github.com/Kangonaut/kistn/blob/main/LICENSE)
+
+</div>
+
+`kistn` is lightweight backup solution using [BorgBackup](https://www.borgbackup.org/), [Borgmatic](https://torsion.org/borgmatic/) and a [Hetzner storage box](https://www.hetzner.com/storage/storage-box/).
+
+### Why does this project exist?
+
+I am very forgetful. I've been using Borgmatic to run my backups for a while now, but every time I want to configure a new backup, I need to look up how to do it again. Sure, I could simply write a guide for myself or ask some AI, but I thought: Why not create a small CLI tool that does everything for me. This also solves my second problem: I always forget to actually do the backups. So why not build a tool that guides you through the setup and also reminds you to do your backups, or even does the backups automatically in the background.
+
+### Should I use `kistn`?
+
+If you are also forgetful or you don't want to read up on how Borgmatic works, then I think this might be a helpful tool for you. I've tried to make the user experience as simple as possible and to guide the user through the setup process. I hope that this means that it can even be used by people, who are not heavy-terminal users. However, it is a CLI tool, so if you'd rather just click some buttons in a fancy GUI, there are surely better options out there. Anyway, this tool is far from being a mature software, but I think it is still usable. If you encounter any problems, you can open an issue and hope for a reply. Sorry, I'm often busy. :)
+
+### Why should I use a Hetzner storage backup box?
+
+There are many other options out there and I'm not saying Hetzner has the best solution. But considering the options I've used so far, it is probably the best and cheapest option I know. `kistn` technically works with any server that is running `borg` and OpenSSH, but it is meant to be used with a Hetzner storage box, because that's what I use. :)
+
+## Getting Started
+
+### 0. Install `uv`
+
+`uv` is a really nice Python package manager. It's technically not required to install `kistn`, but if you don't know what you are doing, simply use `uv`. You won't be disappointed.
+
+1. Check if `uv` is already installed: `uv --version`.
+2. If not, follow the [installation instructions](https://docs.astral.sh/uv/getting-started/installation/) or simply run the following command:
+
+```shell
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### 1. Install `kistn`
+
+1. Install using `uv`: `uv tool install kistn`
+
+### 2. Check Dependencies
+
+1. Run `kistn doctor` to see if your system has all the necessary packages installed.
+
+### 3. (Optional) Add Overdue-Check to Shell Config
+
+If you want to get a reminder to do your overdue backups every time you open a new shell session, then follow the instructions below. The reminder will look something like this:
+
+```shell
+⚠ WARN: basic: Your last backup was 7 days ago. Run `kistn run basic` to start the backup.
+```
+
+1. Open your shell config in your favourite editor. If you are using `zsh`, open `~/.zshrc`. If you are using `bash`, open `.bashrc`.
+2. If you're using `bash` or `zsh`, add the following lines to the very top of your config:
+
+```bash
+# Check for overdue kistn backups
+if [ -f "$HOME/.local/bin/kistn" ]; then
+    "$HOME/.local/bin/kistn" check-overdue
+fi
+```
+
+TODO: add instructions for other shells like `fish`
+
+### 4. Setup the Storage Box
+
+1. Go to the [Hetzner Console](https://console.hetzner.com/) and find your storage box.
+2. Make sure that **SSH Support** and **External Reachability** is enabled.
+3. Keep the page open to look up the hostname, username and port later.
+
+### 5. Create a Remote Connection
+
+1. Run `kistn remote wizard NAME` and follow the instructions. `NAME` should be a simple name to identify your storage box. It probably makes sense to simply adopt the name that is displayed in the Hetzner Console.
+2. Run `kistn remote list` to check if the remote connection is ready to use. It should say `ready` in the `State` column.
+
+**NOTE:** If the `kistn remote wizard` command fails or you interrupt it, you can continue the setup by simply running the command again.
+
+<div align="center">
+    <img src="assets/remote-wizard.png" width="640"/>
+</div>
+
+### 6. Create a Backup Profile
+
+1. Run `kistn profile wizard NAME` and follow the instructions. `NAME` should again be a simple name to identify your backup profile, such as `basic`, `documents`, `university`, `photos`, ...
+2. Make sure you store your paper key at a secure location.
+3. Run `kistn profile list` to check if the profile is ready. Again, it should say `ready` in the `State` column.
+
+**NOTE:** If the `kistn remote profile` command fails or you interrupt it, you can continue the setup by simply running the command again.
+
+<div align="center">
+    <img src="assets/profile-wizard.png" width="640"/>
+</div>
+
+### 7. Create your first Backup
+
+1. Run your first backup using `kistn run PROFILE-NAME`.
+
+### 8. Check when to do your next Backup
+
+1. Use `kistn status` to see when you did your last backup and when the next backup is due. If you chose a frequency of 7, it should say `in 7 days`.
+
+## License
+
+Distributed under the [Apache License 2.0](https://github.com/Kangonaut/kistn/blob/main/LICENSE).

kistn-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "kistn"
+version = "0.1.0"
+description = "A lightweight backup solution using BorgBackup and a Hetzner storage box."
+readme = "README.md"
+requires-python = ">=3.14"
+dependencies = [
+    "packaging>=26.3",
+    "platformdirs>=4.11.3",
+    "pydantic>=2.13.4",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "rich>=15.0.0",
+    "typer>=0.27.1",
+]
+
+[[project.authors]]
+name = "Kangonaut"
+email = "120662571+Kangonaut@users.noreply.github.com"
+
+[project.scripts]
+kistn = "kistn.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

kistn-0.1.0/pyproject.toml.orig

@@ -0,0 +1,25 @@
+[project]
+name = "kistn"
+version = "0.1.0"
+description = "A lightweight backup solution using BorgBackup and a Hetzner storage box."
+readme = "README.md"
+authors = [
+    { name = "Kangonaut", email = "120662571+Kangonaut@users.noreply.github.com" }
+]
+requires-python = ">=3.14"
+dependencies = [
+    "packaging>=26.3",
+    "platformdirs>=4.11.3",
+    "pydantic>=2.13.4",
+    "pyyaml>=6.0.3",
+    "questionary>=2.1.1",
+    "rich>=15.0.0",
+    "typer>=0.27.1",
+]
+
+[project.scripts]
+kistn = "kistn.main:main"
+
+[build-system]
+requires = ["uv_build>=0.12.5,<0.13.0"]
+build-backend = "uv_build"

kistn-0.1.0/src/kistn/borgmatic.py

@@ -0,0 +1,50 @@
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+from kistn import consts, utils
+
+
+class BorgmaticRepository(BaseModel):
+    path: str
+    label: str
+
+
+class BorgmaticCheck(BaseModel):
+    name: str
+
+
+class BorgmaticConfig(BaseModel):
+    source_directories: list[Path]
+    exclude_patterns: list[str] = Field(default_factory=list)
+    repositories: list[BorgmaticRepository]
+
+    # storage and encryption
+    encryption_passphrase: str
+    compression: str
+    archive_name_format: str  # prefix-{hostname}-{now}
+
+    # retention policy
+    keep_daily: int
+    keep_weekly: int
+    keep_monthly: int
+
+    # consistency checks
+    checks: list[BorgmaticCheck]
+
+    @classmethod
+    def get_path(cls, name: str) -> Path:
+        return consts.BORGMATIC_CONFIG_DIR / f"kistn.{name}"
+
+    @classmethod
+    def load(cls, name: str) -> BorgmaticConfig:
+        return utils.io.load_pydantic_from_yaml(BorgmaticConfig, cls.get_path(name))
+
+    def save(self, name: str):
+        # create file with permissions
+        path = consts.BORGMATIC_CONFIG_DIR / f"kistn.{name}"
+        path.touch(mode=0o600, exist_ok=True)
+
+        # serialize to yaml
+        path.parent.mkdir(parents=True, exist_ok=True)
+        utils.io.save_pydantic_to_yaml(self, self.get_path(name))

kistn-0.1.0/src/kistn/commands/__init__.py

@@ -0,0 +1 @@
+from . import profile, remote, system