# AGENTS.md

## Что это

Репозиторий упаковки и развёртывания кастомной сборки FreeRADIUS 3.2.x для
hotspot/captive-portal сценариев. Прикладного кода нет: это сборочные Dockerfile,
shell-скрипты, Helm/k8s-манифесты и
конфиги FreeRADIUS. Профиль каркаса: infra-lite.

Главный контекст: [agent/INDEX.md](agent/INDEX.md). Читать перед любыми изменениями.

Сборка и поставка - через Gitea (`git.ahax86.ru`, owner `pub`): Debian-реестр для .deb,
container registry для образа, Helm-реестр для чарта, generic-пакет для hosted-бандла.
Nexus и GitLab больше не используются.

## Порядок чтения в начале сессии

1. `AGENTS.md` (этот файл).
2. `agent/INDEX.md` - назначение, артефакты, режимы развёртывания, версии, риски.

## Структура репозитория

```
VERSION                       ← единый источник версии FreeRADIUS (3.2.8)
.gitea/workflows/release.yaml ← ручной релиз (Gitea Actions): prepare/build-deb/build-image/package-hosted/package-helm
packaging/
  deb/                        ← сборка .deb из исходников FreeRADIUS + rlm_raw, upload в Debian-реестр Gitea
  image/                      ← рантайм-образ (Dockerfile + entrypoint.sh + local-noble.list); ставит .deb, печёт конфиг
  hosted/                     ← bare-metal/VM установка (install.sh, update.sh, systemd, cron, config)
    config/                   ← radiusd.conf, dictionary, clients.conf, mods-enabled/*, sites-enabled/*
    .env / .env_cnf*          ← версия пакета и подстановки (хосты, порты, креды БД)
charts/
  freeradius/                 ← продуктовый Helm-чарт (Deployment, ConfigMap, Secret, PVC, Service)
```

## Инструменты и команды

- Сборка/выкладка - только через Gitea Actions (`.gitea/workflows/release.yaml`, `workflow_dispatch`).
- Версия задаётся в `VERSION`; CI выводит из неё тег/пин/appVersion и падает при рассинхроне.
- Локальная сборка .deb: `docker build packaging/deb -f packaging/deb/Dockerfile --build-arg RADIUS_TAG=release_3_2_8 --build-arg RLM_RAW_BRANCH=v3.2.4 -t freerad-builder:3.2.8`
- Локальная сборка образа: `docker build -f packaging/image/Dockerfile --build-arg PKG_VERSION=3.2.8+git -t freeradius:3.2.8 .` (контекст = корень).
- Тест hosted: `cd packaging/hosted && docker build . -t hosted:test -f Dockerfile`
- Установка на ноду (bare-metal): `packaging/hosted/install.sh` (root), обновление версии: `packaging/hosted/update.sh`.
- Чарт: `helm lint charts/freeradius --set db.password=test`, `helm template charts/freeradius --set db.password=test`.
- Линтеров/тестов кода в репозитории нет.

## Правила репо

1. Ничего не публиковать (push, PR, CI-стейдж, деплой) без явной команды пользователя.
2. `git add` строго поимённо. Никогда `git add .` или `git add -A`.
3. `.env` / `.env_cnf` не читать целиком и не коммитить - там креды БД. Проверять
   переменную через grep по `^VAR=`. `.env_cnf` хранит секреты и не должен попадать в git.
4. Деструктивные действия с прод-нодами, БД и k8s - только с явного подтверждения.
5. Изменился конфиг, версия, хост или инвариант - синхронно отразить в `agent/INDEX.md`.
6. Долгоживущие решения фиксируются в `agent/INDEX.md`. Журнал сессий не ведётся по умолчанию.
7. Документация краткая и строгая: без галлюцинаций, факты берём из кода и конфигов.

## Язык

Отвечать по-русски, кратко, без длинных тире.