restic-profile-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{restic_profile_cli-0.3.0 → restic_profile_cli-0.4.0}/.ansible-lint

@@ -5,7 +5,7 @@
 # Run with:  ansible-lint
 #            ansible-lint
 
-# Use the 'basic' profile — enforces the most important rules without
+# Use the 'basic' profile - enforces the most important rules without
 # being overly strict for a project that is still evolving.
 # Profiles in ascending order of strictness:
 #   min → basic → moderate → safety → shared → production
@@ -18,6 +18,10 @@ exclude_paths:
   - site/
   - dist/
   - molecule/
+  - examples/
+  - playbooks/host_vars/
+  - playbooks/group_vars/
+  - mkdocs.yaml
 
 # Rules to warn about instead of failing on.
 # These are either stylistic preferences or rules that generate too many

restic_profile_cli-0.3.0/.copier-answers.yaml → restic_profile_cli-0.4.0/.copier-answers.yml

@@ -1,6 +1,7 @@
+---
 # Changes here will be overwritten by Copier; NEVER EDIT MANUALLY
 _commit: c7cc65d
-_src_path: .
+_src_path: git+https://github.com/ak1ra-lab/copier-pyproject.git
 author_email: git@ak1ra.xyz
 author_name: ak1ra
 copyright_date: '2026'

{restic_profile_cli-0.3.0 → restic_profile_cli-0.4.0}/.github/workflows/docs.yaml

@@ -18,7 +18,6 @@ permissions:
   pages: write
   id-token: write
 
-
 concurrency:
   group: docs
   cancel-in-progress: false

restic_profile_cli-0.4.0/AGENTS.md

@@ -0,0 +1,51 @@
+# AGENTS.md
+
+`restic-profile` = a Python CLI (`src/restic_profile/`, tests mirror it under
+`tests/`) plus Ansible roles (`roles/restic_profile`, `roles/restic_rest_server`).
+See `README.md` for the deployment workflow.
+
+## Tooling - use these, not the defaults
+
+`just <recipe>` is a convenience wrapper for humans; each recipe is a thin
+`uv run ...` (see `justfile`). Agents can call `uv run ...` directly when that is
+more flexible - the two are equivalent, not mutually exclusive.
+
+- Env/deps: **uv** (`just sync` = `uv sync --group dev`). Never `pip`/`poetry`/`pipenv`.
+- Lint+format: **ruff** (`just lint` = `uv run ruff check --fix` then
+  `uv run ruff format`, over `src/ tests/ plugins/`). Never `black`/`isort`/`flake8`.
+- Typecheck: **ty** (astral-sh/ty), `src/ plugins/` only
+  (`just typecheck` = `uv run ty check src/ plugins/`). Never `mypy`.
+- Tests: **pytest**. `just test *ARGS` = `uv run pytest -v {{ARGS}} tests/` - ARGS
+  go *before* `tests/`, so `just test -k <pattern>`. Or run
+  `uv run pytest -v tests/test_file.py` directly.
+- Docs: `just docs-build` = `NO_MKDOCS_2_WARNING=1 uv run mkdocs build`.
+- Build: `just build` = `uv build`.
+
+Python changes MUST pass lint, typecheck, and test before commit.
+
+## Ansible (self-contained layout)
+
+`ansible.cfg` pins `roles_path=./roles` and `collections_path=./.ansible/collections`
+and never reaches user-level/parent paths. Playbooks reference roles by FQCN
+(`ak1ra_lab.restic_profile.*`). Before running `ansible-lint` or any playbook,
+install the dependencies into the project-local tree:
+
+```shell
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+```
+
+- `requirements.yaml` deps: `ansible.posix`, `community.general` (usually resolve
+  from user-level ansible) and `ak1ra_lab.general` (not on Galaxy, pulled from git).
+- `ansible-lint` (non-`offline` mode, run from repo root) auto-installs
+  `requirements.yaml` into its own cache dir `./.ansible/collections` - computed
+  by ansible-compat from the project dir, ignoring `ansible.cfg`'s `collections_path`.
+- Molecule scenarios under `roles/*/molecule/` are dormant - don't rely on them.
+
+Ansible changes MUST pass `ansible-lint` before commit.
+
+## Docs (bilingual)
+
+`docs/` is served by mkdocs with the i18n plugin (`docs_structure: suffix`):
+every page has an English `*.md` and a Simplified-Chinese `*.zh.md` sibling
+(e.g. `cli.md` + `cli.zh.md`). When adding or changing user-facing behavior,
+update BOTH language files.

{restic_profile_cli-0.3.0 → restic_profile_cli-0.4.0}/CHANGELOG.md

@@ -5,15 +5,41 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-08-11
+
+### Added
+
+- Multi-Linux-distro support in Ansible roles (`restic_profile`,
+  `restic_rest_server`): Arch, Debian, RedHat, and SUSE, with per-distro
+  package-name mappings in `vars/*.yml` and an `os_family` preflight
+  check; replace `ansible.builtin.apt` with `ansible.builtin.package`
+
+### Changed
+
+- Rename `install_source` value `apt` to `package` in both roles
+  (breaking for existing inventory/group_vars)
+- Move the `restic-rest-server` env file to `/etc/restic-rest-server/env`
+- Pin `ansible.cfg` `roles_path` and `collections_path` to project-local
+  paths (`./roles`, `./.ansible/collections`); rename `requirements.yml`
+  to `requirements.yaml`
+- Add `restic_profile_file_prefix` vars for customizing managed file
+  paths
+
+### Fixed
+
+- Only run `apt update_cache` on Debian-family hosts when
+  `install_source == 'package'`
+- Correct `loop_control.label` typo in role tasks
+
 ## [0.3.0] - 2026-07-13
 
 ### Added
 
 - Per-profile systemd user-scope support via `systemd_scope: user` and
-  `systemd_user` fields — deploys config to `~/.config/restic-profile/`
+  `systemd_user` fields - deploys config to `~/.config/restic-profile/`
   and systemd units to `~/.config/systemd/user/` with automatic
   `loginctl enable-linger` and `XDG_RUNTIME_DIR` handling
-- CLI config resolution via XDG search path — when `--config` is omitted,
+- CLI config resolution via XDG search path - when `--config` is omitted,
   searches `~/.config/restic-profile/restic-profile.toml` then falls back
   to `/etc/restic-profile/restic-profile.toml`
 
@@ -34,7 +60,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `RESTIC_COMPRESSION`, `RESTIC_PACK_SIZE`, and `HTTP_PROXY`
 - Runtime environment variable injection at profile level
   (`[profiles.<name>.env]`) for hook credentials such as `PGPASSWORD`,
-  `MYSQL_PWD` — applied after repository env so profile env takes precedence
+  `MYSQL_PWD` - applied after repository env so profile env takes precedence
 - Runtime environment variable injection at notify channel level
   (`[notify.<name>.env]`) for proxy settings that only affect notification
   HTTP calls

restic_profile_cli-0.4.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.5
+Name: restic-profile-cli
+Version: 0.4.0
+Summary: Profile-based restic wrapper with Ansible deployment support
+Project-URL: Homepage, https://github.com/ak1ra-lab/restic-profile
+Project-URL: Repository, https://github.com/ak1ra-lab/restic-profile
+Project-URL: Documentation, https://ak1ra-lab.github.io/restic-profile/
+Author-email: ak1ra <git@ak1ra.xyz>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ansible,backup,restic
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: argcomplete>=3.7.0
+Requires-Dist: chaos-utils>=0.5.0
+Requires-Dist: jinja2>=3.1.2
+Requires-Dist: pydantic>=2.13.3
+Description-Content-Type: text/markdown
+
+# restic-profile
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
+[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/restic-profile/)
+
+Profile-based restic wrapper, deployed with Ansible.
+
+This repository is an Ansible collection (`ak1ra_lab.restic_profile`) that
+installs and configures the `restic-profile` CLI on local or remote hosts:
+
+- **restic-profile** CLI - reads a TOML config and runs `restic backup` /
+  `forget` / `prune` with hooks and IM notifications.
+- **restic_profile** role - deploys the CLI, renders the TOML config, and
+  manages one systemd timer per profile (including user-level `systemd_scope: user`).
+- **restic_rest_server** role - deploys a [rest-server][rs] instance for remote
+  backup storage.
+
+## Deploy with Ansible
+
+You need Ansible on the control node - see [Ansible toolchain](docs/ansible-toolchain.md)
+for a uv-based setup. Clone the repo and install this collection with its
+dependencies into the project-local tree:
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install --collections-path .ansible/collections -r requirements.yaml
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+Then pick an example from [Ansible examples](docs/restic-profile/examples.md),
+fill in your host_vars, and run the playbook. Building restic from source
+(`restic_profile_restic_install_source: go_build`) also needs a `go` toolchain on
+the control node.
+
+## Development
+
+Only needed to work on `src/restic_profile` or the roles and plugins:
+
+```shell
+uv sync --group dev
+just lint
+just typecheck
+just test
+ansible-lint
+```
+
+To develop `ak1ra_lab.general` alongside this repo, clone
+[ansible-collection-general][acg] next to this checkout and run
+`just ansible-collection-install` - it installs this collection plus your local
+`../ansible-collection-general` (skipping `ansible.posix`/`community.general`,
+which come from your user-level Ansible).
+
+## Documentation
+
+<https://ak1ra-lab.github.io/restic-profile/> - configuration lives in `mkdocs.yml`.
+
+[rs]: https://github.com/restic/rest-server
+[acg]: https://github.com/ak1ra-lab/ansible-collection-general

restic_profile_cli-0.4.0/README.md

@@ -0,0 +1,63 @@
+# restic-profile
+
+**English** | [简体中文](README.zh-CN.md)
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
+[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/restic-profile/)
+
+Profile-based restic wrapper, deployed with Ansible.
+
+This repository is an Ansible collection (`ak1ra_lab.restic_profile`) that
+installs and configures the `restic-profile` CLI on local or remote hosts:
+
+- **restic-profile** CLI - reads a TOML config and runs `restic backup` /
+  `forget` / `prune` with hooks and IM notifications.
+- **restic_profile** role - deploys the CLI, renders the TOML config, and
+  manages one systemd timer per profile (including user-level `systemd_scope: user`).
+- **restic_rest_server** role - deploys a [rest-server][rs] instance for remote
+  backup storage.
+
+## Deploy with Ansible
+
+You need Ansible on the control node - see [Ansible toolchain](docs/ansible-toolchain.md)
+for a uv-based setup. Clone the repo and install this collection with its
+dependencies into the project-local tree:
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install --collections-path .ansible/collections -r requirements.yaml
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+Then pick an example from [Ansible examples](docs/restic-profile/examples.md),
+fill in your host_vars, and run the playbook. Building restic from source
+(`restic_profile_restic_install_source: go_build`) also needs a `go` toolchain on
+the control node.
+
+## Development
+
+Only needed to work on `src/restic_profile` or the roles and plugins:
+
+```shell
+uv sync --group dev
+just lint
+just typecheck
+just test
+ansible-lint
+```
+
+To develop `ak1ra_lab.general` alongside this repo, clone
+[ansible-collection-general][acg] next to this checkout and run
+`just ansible-collection-install` - it installs this collection plus your local
+`../ansible-collection-general` (skipping `ansible.posix`/`community.general`,
+which come from your user-level Ansible).
+
+## Documentation
+
+<https://ak1ra-lab.github.io/restic-profile/> - configuration lives in `mkdocs.yml`.
+
+[rs]: https://github.com/restic/rest-server
+[acg]: https://github.com/ak1ra-lab/ansible-collection-general

restic_profile_cli-0.4.0/README.zh-CN.md

@@ -0,0 +1,59 @@
+# restic-profile
+
+[English](README.md) | **简体中文**
+
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/ak1ra-lab/restic-profile/.github%2Fworkflows%2Fpublish-to-pypi.yaml)](https://github.com/ak1ra-lab/restic-profile/actions/workflows/publish-to-pypi.yaml)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli)](https://pypi.org/project/restic-profile-cli/)
+[![PyPI - Version](https://img.shields.io/pypi/v/restic-profile-cli?label=test-pypi&pypiBaseUrl=https%3A%2F%2Ftest.pypi.org)](https://test.pypi.org/project/restic-profile-cli/)
+[![Docs](https://img.shields.io/badge/docs-online-0a7ea4)](https://ak1ra-lab.github.io/restic-profile/)
+
+基于配置文件的 restic 自动化工具，通过 Ansible 部署。
+
+本仓库是一个 Ansible 集合（`ak1ra_lab.restic_profile`），用于在本地或远程主机上
+安装并配置 `restic-profile` CLI：
+
+- **restic-profile** CLI - 读取 TOML 配置文件，运行 `restic backup` / `forget` /
+  `prune`，支持钩子与即时通讯通知。
+- **restic_profile** 角色 - 部署 CLI、渲染 TOML 配置，并为每个 profile 管理一个
+  systemd 定时器（含用户级 `systemd_scope: user`）。
+- **restic_rest_server** 角色 - 部署 [rest-server][rs] 实例，提供远程备份存储。
+
+## 使用 Ansible 部署
+
+控制节点需要 Ansible - 参见 [Ansible 工具链](docs/ansible-toolchain.zh.md) 了解基于
+uv 的搭建方式。克隆仓库并把本 collection 及其依赖安装到项目本地目录：
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install --collections-path .ansible/collections -r requirements.yaml
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+然后从 [Ansible 示例](docs/restic-profile/examples.zh.md) 中选择一个示例，填写你的
+host_vars，再运行 playbook。若从源码构建 restic
+（`restic_profile_restic_install_source: go_build`），控制节点还需要 `go` 工具链。
+
+## 开发
+
+仅在需要修改 `src/restic_profile` 或角色、插件时才需要：
+
+```shell
+uv sync --group dev
+just lint
+just typecheck
+just test
+ansible-lint
+```
+
+如需与本仓库一起开发 `ak1ra_lab.general`，把 [ansible-collection-general][acg]
+克隆到本仓库同级目录，再运行 `just ansible-collection-install` - 它会安装本
+collection 以及你本地的 `../ansible-collection-general`（`ansible.posix`、
+`community.general` 则来自用户级别的 Ansible）。
+
+## 文档
+
+<https://ak1ra-lab.github.io/restic-profile/> - 文档配置存储在 `mkdocs.yml` 中。
+
+[rs]: https://github.com/restic/rest-server
+[acg]: https://github.com/ak1ra-lab/ansible-collection-general

{restic_profile_cli-0.3.0 → restic_profile_cli-0.4.0}/ansible.cfg

@@ -16,8 +16,8 @@ inventory_ignore_extensions=~, .orig, .bak, .retry, .pyc, .pyo, .creds, .gpg
 force_valid_group_names=ignore
 
 # paths
-roles_path=./roles:~/.ansible/roles
-collections_path=../../../../collections:~/.ansible/collections
+roles_path=./roles
+collections_path=./.ansible/collections
 
 # output
 callbacks_enabled=ansible.posix.profile_tasks, ansible.posix.timer

restic_profile_cli-0.4.0/docs/ansible-toolchain.md

@@ -0,0 +1,78 @@
+# Ansible toolchain
+
+Project-neutral notes for setting up an Ansible authoring toolchain with `uv`,
+and for understanding how `ansible-lint` resolves collection paths. Copy this
+page into any repository that ships an Ansible collection.
+
+## Install the toolchain with uv
+
+[ansible-dev-tools][adt] bundles `ansible-lint`, `ansible-navigator`, `molecule`,
+`ansible-creator`, and friends behind a single `adt` entry point. The upstream
+docs install it with `pip`/`pipx`; the `uv` recipe below is an equivalent that
+keeps everything in one uv-managed tool environment:
+
+```shell
+uv tool install ansible-dev-tools \
+  --with-executables-from ansible-builder \
+  --with-executables-from ansible-core \
+  --with-executables-from ansible-creator \
+  --with-executables-from ansible-dev-environment \
+  --with-executables-from ansible-lint \
+  --with-executables-from ansible-navigator \
+  --with-executables-from ansible-sign \
+  --with-executables-from molecule \
+  --with molecule-plugins[podman] \
+  --with ansible
+```
+
+- `--with-executables-from` exposes each bundled tool's own entry point on
+  `PATH` (otherwise only `adt` is linked).
+- `--with ansible` adds the full `ansible` PyPI package (the batteries-included
+  collection bundle) alongside `ansible-core`, so common Galaxy collections such
+  as `ansible.posix` and `community.general` resolve at user level without a
+  per-project copy.
+- Add more runtime dependencies as needed, e.g.
+  `--with boto3 --with google-auth --with proxmoxer`.
+
+Verify with `adt --version`.
+
+!!! note
+    The `uv tool install` invocation above is **not** documented upstream - it is
+    a community recipe. See [the official installation docs][adt] for the supported installers.
+
+## Self-contained collection paths
+
+To keep a repository's Ansible setup hermetic - never reaching into user-level or
+parent directories - pin the paths in a project-local `ansible.cfg`:
+
+```ini
+[defaults]
+roles_path=./roles
+collections_path=./.ansible/collections
+```
+
+Install the collection's dependencies into that tree. If the playbooks reference
+the collection's own roles by FQCN (`namespace.collection.*`), install the
+collection itself there too:
+
+```shell
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+## Where ansible-lint installs collections
+
+`ansible-lint` does **not** honor `collections_path` from `ansible.cfg` when it
+auto-installs `requirements.yml` / `requirements.yaml`. Internally it uses
+`ansible-compat`, which derives a cache directory from the **project directory**:
+
+- Run from the project root (non-`offline` mode), it installs into
+  `./.ansible/collections` - regardless of what `collections_path` says.
+- `offline: true` in the ansible-lint config disables the auto-install entirely.
+- If the project root is not writable, it falls back to a temporary directory.
+
+Pinning `collections_path` to `./.ansible/collections` therefore matches
+`ansible-lint`'s own behavior: linting and playbook runs share one collection
+tree, and nothing leaks to the user-level `~/.ansible`.
+
+[adt]: https://ansible.readthedocs.io/projects/dev-tools/

restic_profile_cli-0.4.0/docs/ansible-toolchain.zh.md

@@ -0,0 +1,75 @@
+# Ansible 工具链
+
+与具体项目无关的说明：如何用 `uv` 搭建 Ansible 开发工具链，以及 `ansible-lint`
+如何解析 collection 路径。可以把本页直接复制到任何附带 Ansible 集合的仓库中。
+
+## 用 uv 安装工具链
+
+[ansible-dev-tools][adt] 将 `ansible-lint`、`ansible-navigator`、`molecule`、
+`ansible-creator` 等工具捆绑在单一的 `adt` 入口点之后。上游文档使用 `pip`/`pipx`
+安装；下面的 `uv` 方式与之等价，并把一切放进单一的 uv 管理工具环境中：
+
+```shell
+uv tool install ansible-dev-tools \
+  --with-executables-from ansible-builder \
+  --with-executables-from ansible-core \
+  --with-executables-from ansible-creator \
+  --with-executables-from ansible-dev-environment \
+  --with-executables-from ansible-lint \
+  --with-executables-from ansible-navigator \
+  --with-executables-from ansible-sign \
+  --with-executables-from molecule \
+  --with molecule-plugins[podman] \
+  --with ansible
+```
+
+- `--with-executables-from` 将每个捆绑工具自身的入口点暴露到 `PATH`
+  （否则只会链接 `adt`）。
+- `--with ansible` 会在 `ansible-core` 之外额外安装完整的 `ansible` PyPI 包
+  （batteries-included 的 collection 集合），因此 `ansible.posix`、
+  `community.general` 等常见 Galaxy collection 可在用户级别解析，无需每个项目各存一份。
+- 按需追加更多运行时依赖，例如
+  `--with boto3 --with google-auth --with proxmoxer`。
+
+用 `adt --version` 查看版本。
+
+!!! note
+上面的 `uv tool install` 命令**并未**记录在上游文档中 - 这是社区总结的用法。
+受支持的安装方式请参见[官方安装文档][adt]。
+
+## 自包含的 collection 路径
+
+要让仓库的 Ansible 配置保持隔离 - 绝不触及用户级别或上级目录 - 在项目本地的
+`ansible.cfg` 中固定这些路径：
+
+```ini
+[defaults]
+roles_path=./roles
+collections_path=./.ansible/collections
+```
+
+把 collection 的依赖安装到该目录树。如果 playbook 通过 FQCN
+（`namespace.collection.*`）引用 collection 自身的角色，也把该 collection 本身
+安装进去：
+
+```shell
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+## ansible-lint 把 collection 安装到哪里
+
+在自动安装 `requirements.yml` / `requirements.yaml` 时，`ansible-lint`
+**不会**遵循 `ansible.cfg` 中的 `collections_path`。它内部使用 `ansible-compat`，
+后者根据**项目目录**推导出一个缓存目录：
+
+- 从项目根目录运行（非 `offline` 模式）时，它会安装到 `./.ansible/collections`
+  - 无论 `collections_path` 设为什么。
+- ansible-lint 配置中的 `offline: true` 会完全禁用该自动安装。
+- 如果项目根目录不可写，则回退到临时目录。
+
+因此把 `collections_path` 固定为 `./.ansible/collections` 恰好与 `ansible-lint`
+自身的行为一致：lint 与 playbook 运行共享同一份 collection 目录树，且不会泄漏到
+用户级别的 `~/.ansible`。
+
+[adt]: https://ansible.readthedocs.io/projects/dev-tools/

restic_profile_cli-0.4.0/docs/index.md

@@ -0,0 +1,56 @@
+# restic-profile
+
+Profile-based [restic](https://restic.net/) wrapper, deployed with Ansible.
+
+This project is an Ansible collection (`ak1ra_lab.restic_profile`) that installs
+and configures the `restic-profile` CLI on local or remote hosts:
+
+- **restic-profile** CLI - reads a TOML config and runs `restic backup` /
+  `forget` / `prune` with hooks and IM notifications.
+- **restic_profile** role - deploys the CLI, renders the TOML config, and manages
+  one systemd timer per profile (including user-level `systemd_scope: user`).
+- **restic_rest_server** role - deploys a [rest-server](https://github.com/restic/rest-server)
+  instance for remote backup storage.
+
+## Deploy with Ansible
+
+You need Ansible on the control node - see [Ansible toolchain](ansible-toolchain.md)
+for a uv-based setup. Clone the repo and install this collection with its
+dependencies into the project-local tree:
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+Then pick an example from [restic-profile examples](restic-profile/examples.md)
+and fill in your host_vars. Building restic from source
+(`restic_profile_restic_install_source: go_build`) also needs a `go` toolchain on
+the control node.
+
+## Standalone CLI (without Ansible)
+
+The CLI is also published on PyPI for manual or cron-driven use - no Ansible,
+root, or systemd required:
+
+```shell
+uv tool install restic-profile-cli
+restic-profile -c /path/to/my.toml --check
+restic-profile -c /path/to/my.toml myprofile
+```
+
+Start from the [TOML config template](restic-profile/toml-config.md).
+
+## Pages
+
+| You want to...                              | Start here                                            |
+| ------------------------------------------- | ----------------------------------------------------- |
+| Deploy backup profiles with Ansible         | [Ansible examples](restic-profile/examples.md)        |
+| Set up the Ansible toolchain                | [Ansible toolchain](ansible-toolchain.md)             |
+| Write a TOML config for use without Ansible | [TOML config template](restic-profile/toml-config.md) |
+| Understand CLI flags                        | [CLI reference](restic-profile/cli.md)                |
+| Deploy a backup server (rest-server)        | [restic-rest-server](restic-rest-server.md)           |
+
+See `roles/restic_profile/defaults/main.yaml` for all role variables and their defaults.

restic_profile_cli-0.4.0/docs/index.zh.md

@@ -0,0 +1,53 @@
+# restic-profile
+
+基于配置文件的 [restic](https://restic.net/) 自动化工具，通过 Ansible 部署。
+
+本项目是一个 Ansible 集合（`ak1ra_lab.restic_profile`），用于在本地或远程主机上
+安装并配置 `restic-profile` CLI：
+
+- **restic-profile** CLI - 读取 TOML 配置文件，运行 `restic backup` / `forget` /
+  `prune`，支持钩子与即时通讯通知。
+- **restic_profile** 角色 - 部署 CLI、渲染 TOML 配置，并为每个 profile 管理一个
+  systemd 定时器（含用户级 `systemd_scope: user`）。
+- **restic_rest_server** 角色 - 部署 [rest-server](https://github.com/restic/rest-server)
+  实例，提供远程备份存储。
+
+## 使用 Ansible 部署
+
+控制节点需要 Ansible - 参见 [Ansible 工具链](ansible-toolchain.md) 了解基于 uv 的
+搭建方式。克隆仓库并把本 collection 及其依赖安装到项目本地目录：
+
+```shell
+git clone https://github.com/ak1ra-lab/restic-profile.git
+cd restic-profile
+ansible-galaxy collection install -r requirements.yaml -p ./.ansible/collections
+ansible-galaxy collection install --force --collections-path .ansible/collections .
+```
+
+然后从 [restic-profile 示例](restic-profile/examples.md) 中选择一个示例并填写你的
+host_vars。若从源码构建 restic（`restic_profile_restic_install_source: go_build`），
+控制节点还需要 `go` 工具链。
+
+## 独立 CLI（无需 Ansible）
+
+该 CLI 也发布到 PyPI，可用于手动或 cron 驱动的场景 - 无需 Ansible、root 或 systemd：
+
+```shell
+uv tool install restic-profile-cli
+restic-profile -c /path/to/my.toml --check
+restic-profile -c /path/to/my.toml myprofile
+```
+
+可以从 [TOML 配置模板](restic-profile/toml-config.md) 开始。
+
+## 页面
+
+| 你想...                             | 从这里开始                                     |
+| ----------------------------------- | ---------------------------------------------- |
+| 使用 Ansible 部署备份配置文件       | [Ansible 示例](restic-profile/examples.md)     |
+| 搭建 Ansible 工具链                 | [Ansible 工具链](ansible-toolchain.md)         |
+| 编写用于非 Ansible 场景的 TOML 配置 | [TOML 配置模板](restic-profile/toml-config.md) |
+| 了解 CLI 参数                       | [CLI 参考](restic-profile/cli.md)              |
+| 部署备份服务器 (rest-server)        | [restic-rest-server](restic-rest-server.md)    |
+
+参见 `roles/restic_profile/defaults/main.yaml` 了解所有角色变量及其默认值。