Add project documentation
This commit is contained in:
@@ -0,0 +1,83 @@
|
|||||||
|
# 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.
|
||||||
@@ -0,0 +1,157 @@
|
|||||||
|
# vbevdev
|
||||||
|
|
||||||
|
Self-hosted инфраструктурный стек, управляемый через Docker Compose.
|
||||||
|
|
||||||
|
Репозиторий содержит Compose-описание сервисов, workflow для деплоя и пример переменных окружения. Runtime-данные и секреты намеренно не хранятся в Git.
|
||||||
|
|
||||||
|
## Сервисы
|
||||||
|
|
||||||
|
| Сервис | Image | Назначение |
|
||||||
|
| --- | --- | --- |
|
||||||
|
| `prx` | `jc21/nginx-proxy-manager:2.15.1` | Nginx Proxy Manager для reverse proxy, HTTP/HTTPS и сертификатов. |
|
||||||
|
| `pwd` | `vaultwarden/server:latest` | Vaultwarden, менеджер паролей. |
|
||||||
|
| `mon` | `henrygd/beszel` | Beszel monitoring hub. |
|
||||||
|
| `mon-agent` | `henrygd/beszel-agent` | Beszel monitoring agent с доступом к Docker socket. |
|
||||||
|
| `cld` | `nextcloud:30.0.6` | Nextcloud. |
|
||||||
|
| `git` | `docker.gitea.com/gitea:1.26.2` | Gitea server. |
|
||||||
|
| `git-runner` | `gitea/act_runner:latest` | Gitea Actions runner. |
|
||||||
|
| `sup-hbbs` | `rustdesk/rustdesk-server:latest` | RustDesk ID/rendezvous server. |
|
||||||
|
| `sup-hbbr` | `rustdesk/rustdesk-server:latest` | RustDesk relay server. |
|
||||||
|
|
||||||
|
Docker network по умолчанию называется `vbevdev`.
|
||||||
|
|
||||||
|
## Конфигурация
|
||||||
|
|
||||||
|
Создайте локальный `.env` из `.env.example` и задайте значения для своей среды:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
cp .env.example .env
|
||||||
|
```
|
||||||
|
|
||||||
|
Обязательные переменные:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
BESZEL_HUB_URL=http://mon.localhost
|
||||||
|
NEXTCLOUD_DOMAIN=cld.localhost
|
||||||
|
GITEA_URL=http://git:3000
|
||||||
|
RUSTDESK_DOMAIN=sup.local
|
||||||
|
```
|
||||||
|
|
||||||
|
Перед запуском сервисов, которым нужны секреты, создайте файлы:
|
||||||
|
|
||||||
|
```text
|
||||||
|
secrets/vaultwarden_admin_token.txt
|
||||||
|
secrets/beszel_agent_key.txt
|
||||||
|
secrets/beszel_agent_token.txt
|
||||||
|
secrets/gitea_runner_registration_token.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Рекомендуемые права:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
chmod 700 secrets
|
||||||
|
chmod 600 secrets/*.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
Не коммитьте `.env`, `secrets/` и `data/`. В них находятся локальная конфигурация, credentials, базы данных, пользовательские файлы, сгенерированные ключи, сертификаты и другое runtime-состояние.
|
||||||
|
|
||||||
|
## Локальные операции
|
||||||
|
|
||||||
|
Проверить Compose-файл:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose config
|
||||||
|
```
|
||||||
|
|
||||||
|
Запустить или обновить стек:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
Посмотреть состояние и логи:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose ps
|
||||||
|
docker compose logs -f <service>
|
||||||
|
```
|
||||||
|
|
||||||
|
Скачать новые images и пересоздать контейнеры:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose pull
|
||||||
|
docker compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
Остановить стек без удаления runtime-данных:
|
||||||
|
|
||||||
|
```sh
|
||||||
|
docker compose down
|
||||||
|
```
|
||||||
|
|
||||||
|
## Данные
|
||||||
|
|
||||||
|
Persistent-данные контейнеров монтируются в `./data`:
|
||||||
|
|
||||||
|
```text
|
||||||
|
data/nginx-proxy-manager/
|
||||||
|
data/vaultwarden/
|
||||||
|
data/beszel/
|
||||||
|
data/nextcloud/
|
||||||
|
data/gitea/
|
||||||
|
data/rustdesk/
|
||||||
|
```
|
||||||
|
|
||||||
|
Эта директория является runtime-состоянием, а не исходным кодом. Делайте backup перед destructive Docker-командами, изменением volume, миграциями и обновлениями stateful-сервисов.
|
||||||
|
|
||||||
|
## Деплой
|
||||||
|
|
||||||
|
Деплой описан в `.gitea/workflows/deploy.yaml` и запускается вручную через `workflow_dispatch`.
|
||||||
|
|
||||||
|
Workflow деплоя:
|
||||||
|
|
||||||
|
1. Забирает репозиторий.
|
||||||
|
2. Нормализует имя ref/branch для имени удаленного Compose-файла.
|
||||||
|
3. Настраивает SSH через `.gitea/actions/configure-ssh-client`.
|
||||||
|
4. Опционально создает архив `data/`, если `DEPLOY_BACKUP_ENABLED` равен `true`.
|
||||||
|
5. Копирует `docker-compose.yml` на сервер как `docker-compose-<ref>.yml`.
|
||||||
|
6. Создает на сервере `.env` и `secrets/*.txt` из Gitea variables и secrets.
|
||||||
|
7. Запускает `docker compose -f docker-compose-<ref>.yml up -d --remove-orphans`.
|
||||||
|
8. Отправляет Telegram-уведомление об успехе или ошибке и прикладывает deploy log.
|
||||||
|
|
||||||
|
Используемые Gitea variables:
|
||||||
|
|
||||||
|
```text
|
||||||
|
DEPLOY_DIRECTORY
|
||||||
|
DEPLOY_BACKUP_ENABLED
|
||||||
|
DEPLOY_DRY_RUN_ENABLED
|
||||||
|
BESZEL_HUB_URL
|
||||||
|
GIT_URL
|
||||||
|
NEXTCLOUD_DOMAIN
|
||||||
|
RUSTDESK_DOMAIN
|
||||||
|
```
|
||||||
|
|
||||||
|
Используемые Gitea secrets:
|
||||||
|
|
||||||
|
```text
|
||||||
|
SSH_HOST
|
||||||
|
SSH_USERNAME
|
||||||
|
SSH_PASSWORD
|
||||||
|
BESZEL_AGENT_KEY
|
||||||
|
BESZEL_AGENT_TOKEN
|
||||||
|
RUNNER_REGISTRATION_TOKEN
|
||||||
|
VAULTWARDEN_ADMIN_TOKEN
|
||||||
|
TELEGRAM_DEPLOY_BOT_TOKEN
|
||||||
|
TELEGRAM_DEPLOY_CHAT_ID
|
||||||
|
PROXY_URL
|
||||||
|
```
|
||||||
|
|
||||||
|
Workflow `.gitea/workflows/test_telegram_deploy_bot.yaml` можно запускать вручную для проверки Telegram-уведомлений через настроенный proxy.
|
||||||
|
|
||||||
|
## Сопровождение
|
||||||
|
|
||||||
|
- Запускайте `docker compose config` после изменений в `docker-compose.yml`.
|
||||||
|
- Держите `.env.example` синхронизированным с переменными, которые использует Compose.
|
||||||
|
- Держите Gitea variables/secrets синхронизированными с `.gitea/workflows/deploy.yaml`.
|
||||||
|
- Делайте backup `data/` перед обновлениями, сменой images, изменением volumes и миграциями.
|
||||||
|
- Перед изменением pinned image versions проверяйте release notes stateful-сервисов.
|
||||||
Reference in New Issue
Block a user