Metadata-Version: 2.5
Name: kraken-mirror
Version: 0.1.0.dev20261012192655
Summary: One-way, one-source-to-many-receivers media mirror (Kraken)
Author-email: 8lackangel <r.ablinger@protonmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <3.14,>=3.12
Requires-Dist: aiohttp<4,>=3.10
Requires-Dist: argon2-cffi<26,>=23.1
Requires-Dist: blake3<2,>=1.0
Requires-Dist: cryptography<51,>=44
Requires-Dist: jsonschema<5,>=4.23
Requires-Dist: segno<2,>=1.6
Requires-Dist: tomli-w<2,>=1.0
Description-Content-Type: text/markdown

# Kraken

Kraken is a self-hosted, **one-way** folder mirror for Linux. One source
node keeps a library of files (typically large media: 1–80 GB videos and
audio) and mirrors it to up to a handful of receiver nodes, usually at
other sites. Receivers store plain files and folders you can use directly;
no restore tool is needed. Source and receiver are roles per library, so
one node can share some libraries and receive others at the same time.
New here? Read the [documentation index](docs/README.md) first.

Features:

- **Scheduled, reviewable sync.** Changes go out in bounded plans that a
  receiver can check, approve or hold.
- **Verified, resumable transfers.** Every chunk and every file is checked
  against a BLAKE3 hash computed at the source.
- **Protection against mistakes.** Mass deletes or replacements, such as
  ransomware, are held for approval. Deleted files stay in a 30-day trash.
  A library halts if its disk isn't mounted.
- **Direct, encrypted connections** between nodes, dialled by whichever
  side can reach the other, with human-approved registration (or pairing)
  and no certificate authority. A relay forwards registrations, helps
  nodes find each other when addresses change and finds folders by UUID;
  it never sees file contents or names.

## Requirements

- Rocky Linux 10 or Debian 13, x86_64 or arm64; on other x86_64
  distributions with systemd and glibc 2.34 or newer (Rocky/RHEL 9,
  Debian 12, Ubuntu 22.04 and later) the self-extracting `.run` installer.
- Library storage on a local filesystem at the source. Receivers use XFS,
  ext4, ZFS or btrfs.
- One reachable TCP port (8741) on at least one side of each pair of
  nodes.
- For running from source: Python 3.12 or 3.13.

## Quick start

The standard setup is a relay, a source (the machine with the data) and a
receiver (the machine that gets the copy). Install the package on each,
then follow the [getting-started guide](docs/getting-started.md): it
starts the services and does the rest in the web UI, from creating the
administrator to watching the first sync.

```sh
dnf install kraken-mirror kraken-mirror-selinux   # Rocky Linux 10 (repository: see the guide)
apt install kraken-mirror                         # Debian 13
sudo sh kraken-<version>-linux-x86_64.run         # other distributions (glibc 2.34 or newer)
systemctl enable --now kraken-relay               # on the relay host
systemctl enable --now kraken-node                # on the source and the receiver
```

Then open each node's web UI (<http://127.0.0.1:8740/>) right away: the
first visitor creates the administrator.

CI publishes the packages to the project's Gitea package registry: a
release for every `v*` tag (channels `el10` and `trixie/main`) and a dev
build for every push to master (`el10-dev` and `trixie/dev`); see
[installing](docs/admin-manual.md#installing-upgrading-and-removing).
The relay also comes as a container image for a TLS reverse proxy such as
Nginx Proxy Manager ([`packaging/docker/relay/`](packaging/docker/relay/README.md)).
Packages are built locally with `scripts/pkg/build.sh` (see the
[developer manual](docs/developer-manual.md#building-packages)). For
development:

```sh
uv venv .venv --python 3.13
uv pip install --python .venv/bin/python -e . --group dev
scripts/ci-local.sh
```

## Current state

| Area | State |
|---|---|
| Specification | [v2](specs/kraken_specs_v2.md), with [decisions](docs/decisions.md) and [errata](docs/ERRATA.md) |
| Implementation | P0–P8 complete; P9 (seeding, backup and restore, recovery, scrub, production readiness) complete except the hardware benchmark (P9.7, on the owner's hardware); see the [implementation plan](docs/IMPLEMENTATION_PLAN.md) |
| Tested platforms | RPM on Rocky Linux 10 (bundled Python 3.12.14, SELinux enforcing) and DEB on Debian 13 (bundled Python 3.13.5, AppArmor enforce), x86_64 in VMs; arm64 packages start and sync under emulation; pip on Python 3.12 and 3.13 |

## Documentation

Start with the [documentation index](docs/README.md): what Kraken is, the
words it uses, and which document answers what.

- [Getting started](docs/getting-started.md)
- [User manual](docs/user-manual.md)
- [Admin manual](docs/admin-manual.md)
- [Integration guide](docs/integration-guide.md)
- [Developer manual](docs/developer-manual.md)
- [Security manual](docs/security-manual.md)
- [Restore guide](docs/restore-guide.md)
- [krakenctl command reference](docs/krakenctl.md)

## Authors

- 8lackangel

## License

MIT; see [LICENSE](LICENSE).
