84 lines
4.3 KiB
Markdown
84 lines
4.3 KiB
Markdown
# AGENTS.md
|
||
|
||
Инструкции для AI-агентов и автоматизации, работающих с этим репозиторием.
|
||
|
||
## Форма проекта
|
||
|
||
Это Docker Compose инфраструктурный репозиторий. Основные source-файлы:
|
||
|
||
- `docker-compose.yml`
|
||
- `.env.example`
|
||
- `.gitignore`
|
||
- `.gitea/workflows/*.yaml`
|
||
- `.gitea/actions/*`
|
||
- `README.md`
|
||
- `AGENTS.md`
|
||
|
||
Текущие service aliases в Compose:
|
||
|
||
```text
|
||
prx
|
||
pwd
|
||
mon
|
||
mon-agent
|
||
cld
|
||
git
|
||
git-runner
|
||
sup-hbbs
|
||
sup-hbbr
|
||
```
|
||
|
||
Сохраняйте эти короткие aliases, если пользователь явно не попросил переименовать сервисы и не подтвердил учет deploy-impact.
|
||
|
||
## Секреты и runtime-данные
|
||
|
||
Не читайте, не выводите, не пересказывайте, не копируйте и не коммитьте реальные секреты или runtime-данные.
|
||
|
||
Считайте эти пути sensitive или local-only:
|
||
|
||
- `.env`
|
||
- `secrets/`
|
||
- `data/`
|
||
- database-файлы вроде `*.sqlite3`, `*.sqlite3-shm`, `*.sqlite3-wal`
|
||
- private keys и сгенерированные service credentials
|
||
- certificates и letsencrypt data
|
||
|
||
Используйте `.env.example`, `docker-compose.yml` и workflow-файлы как source of truth для имен переменных и секретов. Если задача требует просмотра реальных secret values или runtime-данных, остановитесь и запросите явное разрешение пользователя.
|
||
|
||
## Правила изменений
|
||
|
||
- Держите изменения узко привязанными к запрошенному infrastructure-поведению.
|
||
- Не выполняйте destructive-операции против `data/`, `secrets/`, Docker volumes или корня проекта без явного разрешения пользователя.
|
||
- Не запускайте `docker compose down -v`, volume pruning, recursive deletion, database migrations или service resets, если пользователь не запросил именно это.
|
||
- При добавлении или изменении Compose-переменной обновляйте `.env.example`, `README.md` и Gitea deploy workflow, если значение нужно при деплое.
|
||
- При добавлении или изменении Compose-секрета обновляйте блок `secrets:`, создание секретов в deploy workflow, `README.md` и соответствующий service environment.
|
||
- Сохраняйте стиль YAML: короткие service aliases, single quotes там, где они уже используются, и существующую indentation-схему.
|
||
- Избегайте unrelated formatting churn в workflow и Compose-файлах.
|
||
|
||
## Валидация
|
||
|
||
Для Compose-изменений запускайте:
|
||
|
||
```sh
|
||
docker compose config
|
||
```
|
||
|
||
Для изменений deploy workflow проверяйте затронутые `.gitea/workflows/*.yaml` и подтверждайте, что нужные variables/secrets описаны в `README.md`.
|
||
|
||
Для documentation-only изменений проверьте, что:
|
||
|
||
- service names совпадают с `docker-compose.yml`;
|
||
- environment variables совпадают с `.env.example`;
|
||
- secret filenames совпадают с Compose-блоком `secrets:`;
|
||
- реальные secret values и runtime-данные не попали в документацию.
|
||
|
||
## Операционный контекст
|
||
|
||
Деплой запускается вручную через Gitea Actions. Deploy workflow подключается к серверу по SSH, записывает `.env` и `secrets/*.txt`, опционально делает backup удаленного `data/` и стартует контейнеры командой:
|
||
|
||
```sh
|
||
docker compose -f docker-compose-<ref>.yml up -d --remove-orphans
|
||
```
|
||
|
||
Workflow может отправлять Telegram-уведомления и прикладывать deploy logs. Изменения deploy-поведения должны учитывать и remote shell commands, и documented Gitea variables/secrets.
|