# Технологический стек

## Control Plane

| Компонент | Роль | Declared / resolved evidence |
|---|---|---|
| Nix | Воспроизводимый dev shell | `flake.nix`, locked nixpkgs revision в `flake.lock` |
| Python | Ansible controller runtime | `pkgs.python3` в `flake.nix`; точная версия зависит от lock |
| ansible-core | Inventory, playbooks, roles | `>=2.19` в `requirements.txt`; locked Nix package на момент аудита 2.21.3 |
| proxmoxer | Proxmox API client | `>=2.3`; locked Nix package на момент аудита 2.3.0 |
| requests | HTTP dependency | `>=2.31`; точная Nix version определяется `flake.lock` |
| ansible.posix | POSIX modules | `>=2.0.0`; installed version не закреплена |
| community.proxmox | Proxmox modules | `>=2.0.0`; installed version не закреплена |
| community.general | Общие modules | `>=10.0.0`; installed version не закреплена |
| ansible-lint | Static validation | Nix package; CI отдельно pin `25.8.2` |
| yamllint | YAML validation | Nix package; CI отдельно pin `1.37.1` |

Nix shell также содержит Git, jq, OpenSSH, curl и GNU Make. Galaxy collections не
устанавливаются автоматически и живут в ignored `ansible/collections/`.

## Managed Runtime

- Proxmox VE/LXC и PBS являются внешними runtime systems; их версии не заданы manifest.
- Debian LXC templates и Docker/systemd используются service playbooks.
- Caddy, OpenVPN и restic устанавливаются/используются на managed hosts; точные
  runtime versions репозиторий не фиксирует.
- Active update-managed container images обычно закреплены `tag@sha256:digest` в
  `ansible/inventory/group_vars/all/services.yml` и service playbooks.
- Исключения: frozen Prometheus images закреплены только тегами, а `docker-test`
  использует smoke image без declared digest.

## Grimmory MCP

| Компонент | Version | Evidence |
|---|---|---|
| Node.js | `>=22` | `tools/grimmory-mcp/package.json` |
| `@modelcontextprotocol/sdk` | `1.30.0` | package manifest и lockfile |
| Zod | `3.25.76` | package manifest и lockfile |
| Grimmory API compatibility | deployed `v3.2.4` | service registry и compatibility code |

Node.js/npm не входят в `flake.nix`; их нужно предоставлять отдельно.

## Setup

```bash
nix develop
ansible-galaxy collection install \
  -r ansible/requirements.yml \
  -p ansible/collections
make -C ansible help
```

`make -C ansible setup` остается venv fallback, но Nix является предпочтительным
контроллерным окружением.

## Validation

```bash
make -C ansible inventory
make -C ansible docs
make -C ansible lint
nix develop -c sh -c \
  'cd ansible && for f in playbooks/*.yml; do ansible-playbook --syntax-check "$f"; done'
npm test --prefix tools/grimmory-mcp
```

`make check`, `make status`, `make backup-audit` и `make openvpn-check` обращаются к
живой инфраструктуре и не являются локальными unit tests. Документационное изменение
не требует их запуска.

## CI

`.gitea/workflows/lint.yml` описывает yamllint, ansible-lint и syntax-check всех
playbooks. Комментарии в самом workflow фиксируют, что Gitea Actions отключены и
runner не зарегистрирован; автоматического gate сейчас нет. MCP tests в workflow
не включены.