Metadata-Version: 2.4
Name: backup-orchestrator
Version: 0.17.0
Summary: Scaffold for backup orchestration services
Author-email: Tomasz Sieprawski <tomasz@sieprawski.pl>
Requires-Python: >=3.13
Provides-Extra: dev
Requires-Dist: build==1.3.0; extra == 'dev'
Requires-Dist: pytest-cov==7.1.0; extra == 'dev'
Requires-Dist: pytest==9.0.3; extra == 'dev'
Requires-Dist: reuse==5.1.1; extra == 'dev'
Requires-Dist: ruff==0.15.12; extra == 'dev'
Requires-Dist: twine==6.2.0; extra == 'dev'
Description-Content-Type: text/markdown

<!--
SPDX-FileCopyrightText: 2026 Tomasz Sieprawski <tomasz@sieprawski.pl>
SPDX-License-Identifier: LicenseRef-Proprietary
-->

# backup-orchestrator

Minimal scaffold for the future backup orchestration server and client.

Current scope:
- installable Python package
- no-op CLI entrypoint
- unit tests
- integration test script
- release script and post-merge release workflow
- Forgejo workflows for checks, integration, release, and conventional commit validation

## Local Usage

Run checks:

```bash
./scripts/check.sh
```

Run the integration test:

```bash
./scripts/test-integration.sh
```

Run the release integration test:

```bash
./scripts/test-integration-release.sh
```

Run the manual restic and Borg benchmark harness:

```bash
./scripts/test-benchmark-restic-cache.sh --runs 5
```

Notes:

- this is a manual benchmark tool, not a normal CI test
- it runs real local `restic` and `borg` repositories against the same synthetic datasets
- it writes JSON output under `./benchmark-results` by default
- use it first on one machine locally, then reuse it on gator and zotac for cross-host measurements
- practical repetition guidance:
  - smoke or harness validation: `--runs 3`
  - first comparative pass: `--runs 10`
  - cheap scenario percentile runs: `--runs 30` to `--runs 100`
  - expensive large-repository scenarios: usually `--runs 5` to `--runs 20`
- current default decision-focused variants are:
  - restic: `default`, `cache-off`, `group-by-paths`, `explicit-parent`, `no-scan`, `ignore-ctime`, `compression-off`, `compression-max`
  - borg: `default`, `files-cache-disabled`
- restic runs use `--read-concurrency 4`; inode checking remains enabled because production sources are not FUSE or pCloud mounts
- use `--scenario-prefixes huge` for the most decision-relevant large Nextcloud-like comparisons
- for light local dry runs, keep `--huge-target-gib` modest and use a native Linux filesystem workdir
- for serious host runs, use a large disposable workdir on representative direct local storage; the completed `100 GiB` gator run is the current practical scale reference, while the slow USB `100 GiB` attempt exceeded 16 hours and larger runs should not be assumed feasible
- large runs need significantly more free workspace than the nominal `--huge-target-gib` target because source data, repository growth, cache state, temp files, and tool-specific working state coexist during the benchmark; plan for a substantial multi-times space multiplier rather than target-size-only headroom

Profile a real source tree before changing synthetic benchmark data:

```bash
python3 scripts/profile-backup-dataset.py /path/to/source --output source-profile.json
```

The profiler is read-only. It reports file-count, byte, extension, size-bucket, top-level-directory, and sampled content entropy/compressibility statistics to guide synthetic benchmark data design.

Run the CLI:

```bash
python -m backup_orchestrator
backup-orchestrator scaffold
```

Restic cache configuration:

- pass `--restic-cache-dir /path/to/persistent/cache` to local or remote
  `backup`, `snapshots`, `restore`, or `prune`
- the value is exported as `RESTIC_CACHE_DIR` to the restic process
- downstreams own the persistent path, capacity, and container mount
- omit the option to retain restic's no-explicit-cache behavior

## Licensing

All code in this repository is proprietary.
All rights reserved.

## Release

Merges to `main` are intended to trigger a package release to the local Forgejo
PyPI registry.

Version bumps are driven by conventional commits:
- breaking changes: major
- `feat`: minor
- `fix`, `ci`, `refactor`, `test`: patch
- `docs`, `chore`: no release
