DmitryandClaude Sonnet 5
d2e1e6876a
- docs/ai/: stable, repo-verified context - README, architecture, tech-stack, edge-cases, plan (confirmed active work only), migration-tofu (the blue-green OpenTofu migration runbook and per-service findings), legacy-warning, links. - AGENTS.md: slimmed to a working contract that points at docs/ai instead of restating it; CLAUDE.md is an adapter that @-includes it. - README.md, ansible/README.md, ansible/roles/README.md, roles/lxc_docker_host/README.md: bring wording in line with the current control plane (Makefile entry point, registry, tofu, memoir-bot gone). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012uoq5AVK8mkBgg83Mq6o5V
69 lines
4.7 KiB
Markdown
69 lines
4.7 KiB
Markdown
# AI Context
|
||
|
||
## Назначение
|
||
|
||
Этот набор документов фиксирует стабильный, подтвержденный репозиторием контекст
|
||
HomeLab. Он дополняет краткий рабочий контракт в [`AGENTS.md`](../../AGENTS.md) и
|
||
не заменяет канонические Ansible inventory/vars или операционные заметки Obsidian.
|
||
|
||
HomeLab управляется как Ansible-first control plane: Proxmox VE/LXC, сетевой
|
||
транспорт, сервисы, резервное копирование, обновления и мониторинг описываются в
|
||
`ansible/`. Прямые изменения на серверах допустимы только для read-only диагностики
|
||
или break-glass восстановления с последующим переносом желаемого состояния в Ansible.
|
||
|
||
## Возможности
|
||
|
||
- создание и настройка LXC через Proxmox API или `pct` по SSH;
|
||
- управление сервисами через Docker/systemd и Docker Compose/systemd;
|
||
- OpenVPN-транспорт и SSH ProxyJump через `ru-vps`;
|
||
- Caddy reverse proxy для публичных сервисов;
|
||
- PBS и offsite restic backups с аудитом свежести;
|
||
- управляемые обновления по схеме backup/audit -> update -> health check;
|
||
- активный Uptime Kuma и сохраненный, но замороженный Prometheus stack;
|
||
- локальный Grimmory MCP с ручной синхронизацией книг в Obsidian.
|
||
|
||
## Форма системы
|
||
|
||
- `ansible/Makefile` является основной ручной точкой входа.
|
||
- `ansible/inventory/hosts.yml` задает хосты, группы и индивидуальные адреса.
|
||
- `ansible/inventory/group_vars/all/services.yml` содержит сводный реестр сервисов,
|
||
но пока программно управляет только генерацией reverse proxy.
|
||
- `ansible/playbooks/` содержит операционные entry points, `ansible/roles/` - роли.
|
||
- `tools/grimmory-mcp/` является отдельным Node.js stdio MCP-процессом.
|
||
- Obsidian vault хранит решения, текущую эксплуатационную картину и журнал работ.
|
||
|
||
## Карта репозитория
|
||
|
||
| Путь | Назначение |
|
||
|---|---|
|
||
| `ansible/Makefile` | Проверки, deploy, update и защищенные операции |
|
||
| `ansible/inventory/` | Канонические хосты, группы, общие и host-specific vars |
|
||
| `ansible/playbooks/` | Операционные Ansible entry points |
|
||
| `ansible/roles/` | Переиспользуемые роли и сохраненный monitoring stack |
|
||
| `ansible/ssh_config` | SSH users, keys, ports и ProxyJump |
|
||
| `.opencode/agents/` | Read-only специализированные агенты HomeLab |
|
||
| `tools/grimmory-mcp/` | Grimmory API и Obsidian sync integration |
|
||
| `archive/2026-07-proxmox-migration/` | История до Ansible control plane, не active source |
|
||
|
||
## Ключевые ограничения
|
||
|
||
- Не хранить secrets в Git или Obsidian.
|
||
- Не считать `--check --diff` полной симуляцией Proxmox provisioning.
|
||
- Не запускать замороженный Prometheus stack без отдельного решения.
|
||
- Не считать generic roles `lxc_docker_host` и `compose_service` подключенными к
|
||
production: активные service playbooks пока остаются источником поведения.
|
||
- Не исправлять обнаруженный технический долг в рамках несвязанной задачи.
|
||
- Не редактировать archive, generated files, installed Galaxy collections или
|
||
`node_modules` как active implementation.
|
||
|
||
## Документы
|
||
|
||
- [`architecture.md`](architecture.md) - observed architecture и data/control flows.
|
||
- [`tech-stack.md`](tech-stack.md) - runtimes, dependencies и команды.
|
||
- [`edge-cases.md`](edge-cases.md) - failure modes, safety gaps и coverage.
|
||
- [`plan.md`](plan.md) - только подтвержденная активная работа.
|
||
- [`migration-tofu.md`](migration-tofu.md) - пошаговый план перехода provisioning
|
||
LXC на OpenTofu по схеме blue-green.
|
||
- [`legacy-warning.md`](legacy-warning.md) - границы legacy/frozen/prototype кода.
|
||
- [`links.md`](links.md) - официальные version-relevant references.
|