diff --git a/00-principles.md b/00-principles.md new file mode 100644 index 0000000..1a8f4be --- /dev/null +++ b/00-principles.md @@ -0,0 +1,33 @@ +# Принципы платформы Gnexus + +## 1. Self-hosted прежде всего +Сервисы разворачиваются на собственной инфраструктуре (VM на гипервизоре, VPS в LAN). +Облачный SaaS — только если нет жизнеспособного self-hosted варианта. + +## 2. Open-source +Предпочтение open-source решениям. Собственный код живёт в GitBucket. + +## 3. Budget-first +Бесплатное и дешёвое — раньше удобного. Платные подписки — осознанное исключение. + +## 4. Секреты +- Секреты никогда не попадают в git, документацию и чат. +- В рантайме — `.env` рядом с сервисом (chmod 600). +- Каноническое хранилище — gnexus-creds. +- В документации — только ссылки на секреты, не значения. Подробнее: [10-platform/secrets.md](10-platform/secrets.md). + +## 5. Safety-first +- Перед рискованной операцией — бэкап и план отката. +- Деструктивные действия (rm, DROP, firewall, рестарт прода) — сначала объявить: что, зачем, откат. + +## 6. Документируй +Каждый сервис получает страницу в gnexus-book при деплое. Подробнее: [30-operations/docs.md](30-operations/docs.md). + +## 7. Единая аутентификация +Пользовательская аутентификация — через gnexus-auth (SSO), а не своя собственная. Подробнее: [10-platform/auth.md](10-platform/auth.md). + +## 8. Единый стиль +UI — через gnexus-ui-kit, а не копирование стилей в каждый сервис. Подробнее: [10-platform/ui.md](10-platform/ui.md). + +## 9. Уведомления через Synapse +Исходящие уведомления (email, Telegram, webhooks) — через хаб Gnexus Synapse. Подробнее: [10-platform/notifications.md](10-platform/notifications.md). diff --git a/10-platform/auth.md b/10-platform/auth.md new file mode 100644 index 0000000..5026d2a --- /dev/null +++ b/10-platform/auth.md @@ -0,0 +1,16 @@ +# Аутентификация: gnexus-auth (SSO) + +Все пользовательские сервисы Gnexus подключаются к центральному SSO — gnexus-auth +(Laravel, auth.gnexus.space). Сервис не создаёт собственную систему пользователей. + +## Правила +- Регистрация OAuth-клиента в gnexus-auth (client_id + client_secret). +- redirect_uri — постоянный HTTPS-адрес сервиса. +- Секреты клиента — в `.env` сервиса и в gnexus-creds, не в git. +- Webhook-события `user.*` (создание/изменение пользователя) подписаны HMAC (`GAUTH_WEBHOOK_SECRET`). +- Готовые клиентские библиотеки: `gnexus-auth-client-py` (Python), `gnexus-auth-client-php` (PHP). + +## Ссылки +- Репозиторий: https://git.gnexus.space/root/gnexus-auth +- Клиенты: `gnexus-auth-client-py`, `gnexus-auth-client-php` +- Факты о сервисе: gnexus-book → `10-systems/services/gnexus-auth.md` diff --git a/10-platform/git.md b/10-platform/git.md new file mode 100644 index 0000000..bd69792 --- /dev/null +++ b/10-platform/git.md @@ -0,0 +1,12 @@ +# Git и GitBucket + +Центральный git-хостинг — GitBucket: https://git.gnexus.space + +## Правила +- Все проекты живут под owner `root`. +- Клон: `https://git.gnexus.space/git/root/.git` +- README в каждом репозитории: что это, как запустить, где документация. +- Документация проекта — в репозитории (`docs/`) и/или gnexus-book; факты об инфраструктуре — в book. +- Приватность: приватные репо для закрытых проектов, публичные — для open-source. +- Не хранить секреты в репозиториях (см. [secrets.md](secrets.md)). +- Ветка по умолчанию: `master`. diff --git a/10-platform/notifications.md b/10-platform/notifications.md new file mode 100644 index 0000000..26bc807 --- /dev/null +++ b/10-platform/notifications.md @@ -0,0 +1,11 @@ +# Уведомления: Gnexus Synapse + +Исходящие уведомления сервисов (email, Telegram, webhooks) идут через хаб Gnexus Synapse. + +## Правила +- Сервис регистрируется в Synapse как источник и шлёт события в хаб. +- Каналы доставки (email, Telegram) настраиваются в Synapse, а не в каждом сервисе. +- Секреты интеграции — в `.env` и gnexus-creds. + +## Ссылки +- Факты: gnexus-book → `10-systems/services/gnexus-synapse.md` diff --git a/10-platform/secrets.md b/10-platform/secrets.md new file mode 100644 index 0000000..3e5eff9 --- /dev/null +++ b/10-platform/secrets.md @@ -0,0 +1,12 @@ +# Секреты + +## Правила +1. Секреты не попадают в git — никогда: код, docs, скрипты, примеры конфигов. +2. В рантайме — `.env` рядом с сервисом, chmod 600, файл в `.gitignore`. +3. Каноническое хранилище — gnexus-creds: каждый сервисный секрет заводится там + с тегами сервиса, `allow_mcp=true`, чувствительные поля `encrypted=true`. +4. В документации — только ссылки (имя секрета в creds), не значения. +5. Ротация — через gnexus-creds + обновление `.env`; старая версия остаётся в истории. + +## Ссылки +- Сервис: https://creds.gnexus.space (для агентов — MCP `gnexus-creds`) diff --git a/10-platform/ui.md b/10-platform/ui.md new file mode 100644 index 0000000..7ccdba9 --- /dev/null +++ b/10-platform/ui.md @@ -0,0 +1,12 @@ +# UI: gnexus-ui-kit + +Визуальный стиль и UI-компоненты — централизованно через gnexus-ui-kit. + +## Правила +- Новые веб-сервисы подключают gnexus-ui-kit как зависимость (есть Vue-адаптер). +- Изменения стиля делаются в ui-kit, а не копируются в сервисы. +- Эстетика: брутализм, тёмная тема, геометрические гротески, JetBrains Mono. + +## Ссылки +- Репозиторий: https://git.gnexus.space/root/gnexus-ui-kit +- Документация: `docs/index.md` в репозитории diff --git a/20-deployment/backups.md b/20-deployment/backups.md new file mode 100644 index 0000000..d31273d --- /dev/null +++ b/20-deployment/backups.md @@ -0,0 +1,13 @@ +# Бэкапы + +## Правила +- Перед рискованным изменением (миграция, апгрейд, реструктуризация) — бэкап. +- БД сервисов — регулярный дамп (cron), хранение на отдельном хосте. +- VM — снапшот перед изменением через гипервизор. +- Бэкап бесполезен, если восстановление не проверено. + +## Минимум для нового сервиса +1. Что бэкапим: БД / данные / конфиги (`.env` отдельно от git). +2. Куда: отдельный хост или NFS-шара. +3. Как часто: по критичности (ежедневно для боевых данных). +4. Как восстановить: инструкция в docs сервиса. diff --git a/20-deployment/domains.md b/20-deployment/domains.md new file mode 100644 index 0000000..595aa88 --- /dev/null +++ b/20-deployment/domains.md @@ -0,0 +1,16 @@ +# Домены и маршруты + +Публичные сервисы публикуются через `*.gnexus.space`. + +## Правила +- Формат поддомена: `.gnexus.space`. +- Базовый маршрут: Internet → external-vps → OpenVPN → internal-proxy-vps → internal-nginx → VM сервиса. +- Новый публичный сервис = поддомен + nginx vhost на internal-nginx + запись в gnexus-book + (traffic-routes + endpoints). +- Актуальную схему TLS и маршрутизации сверять с gnexus-book → `10-systems/traffic-routes/`. + +## Как получить маршрут +1. Определить внутренний адрес сервиса (IP:порт). +2. Завести vhost на internal-nginx-proxy. +3. Прописать поддомен на external-vps. +4. Задокументировать в gnexus-book. diff --git a/20-deployment/hosting.md b/20-deployment/hosting.md new file mode 100644 index 0000000..ff9cf37 --- /dev/null +++ b/20-deployment/hosting.md @@ -0,0 +1,15 @@ +# Где что живёт + +Инфраструктура: гипервизор HP ProLiant DL380 G6 (libvirt VM) + VPS в домашней LAN. +Актуальный список хостов, IP и сервисов — в gnexus-book (инвентарь `hosts`/`services`). + +## Правила выбора хоста для нового сервиса +- Веб-сервисы экосистемы — VM на гипервизоре или VPS в LAN. +- Telegram-боты — VM tgbots. +- Тяжёлые/медиа-нагрузки — отдельные VM (Jellyfin, Transmission). +- Не размещать новое на хостах, уже выполняющих критичную роль, без согласования с владельцем. + +## Правила деплоя +- Код — из GitBucket; деплой воспроизводим (скрипт или инструкция в репо). +- Конфигурация через `.env`, не в коде. +- systemd-юнит для долгоживущих процессов, автостарт после ребута. diff --git a/30-operations/docs.md b/30-operations/docs.md new file mode 100644 index 0000000..a2a29d1 --- /dev/null +++ b/30-operations/docs.md @@ -0,0 +1,14 @@ +# Документирование: gnexus-book + +gnexus-book — каноническая база знаний об инфраструктуре (факты, не правила). + +## Правила +- Каждый задеплоенный сервис получает страницу в gnexus-book + (шаблон: [90-templates/service-doc-template.md](../90-templates/service-doc-template.md)). +- Факты (IP, порты, версии, маршруты) — в book; правила — в handbook. +- Агенты сверяются с book перед действиями с инфраструктурой и обновляют её после изменений. +- Секреты в book запрещены — только ссылки (см. [10-platform/secrets.md](../10-platform/secrets.md)). + +## Ссылки +- Репозиторий: https://git.gnexus.space/root/gnexus-book +- MCP для агентов: `gnexus-book` (search_docs, inventory) diff --git a/30-operations/monitoring.md b/30-operations/monitoring.md new file mode 100644 index 0000000..8340b18 --- /dev/null +++ b/30-operations/monitoring.md @@ -0,0 +1,10 @@ +# Мониторинг и алерты + +## Правила +- Живость сервисов — hard-panel (GHard Monitor) с агентами на хостах. +- Алерты — через Gnexus Synapse (Telegram/email). +- Новый сервис: добавить проверку в hard-panel, настроить алерт в Synapse. +- Логи: journald/systemd; для ботов — отдельный лог-файл + ротация. + +## Ссылки +- Факты: gnexus-book → `10-systems/services/hard-panel.md` diff --git a/90-templates/new-service-checklist.md b/90-templates/new-service-checklist.md new file mode 100644 index 0000000..f2c88c5 --- /dev/null +++ b/90-templates/new-service-checklist.md @@ -0,0 +1,12 @@ +# Чеклист нового сервиса + +- [ ] Репозиторий в GitBucket (`root/`), README по шаблону +- [ ] SSO: OAuth-клиент в gnexus-auth (если есть пользователи) +- [ ] UI: подключён gnexus-ui-kit (если есть веб-интерфейс) +- [ ] Секреты: `.env` (chmod 600) + gnexus-creds, `.gitignore` +- [ ] Уведомления: интеграция с Synapse (если сервис шлёт уведомления) +- [ ] Хост: выбран по [hosting.md](../20-deployment/hosting.md), systemd-юнит, автостарт +- [ ] Домен: поддомен `*.gnexus.space` + nginx vhost (если публичный) +- [ ] Бэкап: что / куда / как часто / восстановление +- [ ] Мониторинг: hard-panel + алерты Synapse +- [ ] Документация: страница в gnexus-book diff --git a/90-templates/service-doc-template.md b/90-templates/service-doc-template.md new file mode 100644 index 0000000..0c92cdf --- /dev/null +++ b/90-templates/service-doc-template.md @@ -0,0 +1,32 @@ +# + +--- +owner: gmikcon +status: active +last_reviewed: YYYY-MM-DD +review_interval: 90d +confidence: high +source_of_truth: +--- + +# + +<Одним абзацем: что это.> + +## Access +- Public URL / internal URL +- Метод аутентификации + +## Infrastructure Path +- Хост, IP, порты (факты — из инвентаря gnexus-book) + +## Deployment +- Репозиторий, способ деплоя, расположение `.env` + +## Backups +- Что / куда / как часто / восстановление + +## Monitoring +- Проверки, алерты + +## Notes diff --git a/README.md b/README.md new file mode 100644 index 0000000..894aad0 --- /dev/null +++ b/README.md @@ -0,0 +1,52 @@ +# Gnexus Handbook + +Единый источник политики, конвенций и инструкций для всех сервисов экосистемы Gnexus. + +## Зачем этот репозиторий + +При создании нового сервиса одни и те же правила приходится повторять каждый раз: +как подключить SSO, где хранить секреты, как получить домен, что документировать. +Этот репозиторий — место, на которое ссылаются вместо повторения. + +## Как этим пользоваться + +### Владельцу +- При постановке задачи на новый сервис: «Конвенции — в gnexus-handbook, раздел X». +- Изменение правила = изменение здесь, а не в очередном чате. + +### Агентам (Navi и другим ИИ) +- Перед созданием нового сервиса прочитай этот README и релевантные разделы. +- Если правило противоречит задаче владельца — владелец прав, но предложи обновить handbook. +- Не копируй правила в другие репозитории и промпты — ссылайся сюда. + +### Сервисам и документации +Ссылайся на конкретный файл через raw-URL: + +``` +https://git.gnexus.space/root/gnexus-handbook/raw/master/ +``` + +## Оглавление + +- [00-principles.md](00-principles.md) — базовые принципы платформы +- `10-platform/` — интеграция с общей инфраструктурой + - [auth.md](10-platform/auth.md) — SSO через gnexus-auth + - [ui.md](10-platform/ui.md) — UI и визуальный стиль + - [notifications.md](10-platform/notifications.md) — уведомления через Gnexus Synapse + - [secrets.md](10-platform/secrets.md) — секреты + - [git.md](10-platform/git.md) — Git и GitBucket +- `20-deployment/` — деплой + - [hosting.md](20-deployment/hosting.md) — где что живёт + - [domains.md](20-deployment/domains.md) — домены и маршруты + - [backups.md](20-deployment/backups.md) — бэкапы +- `30-operations/` — эксплуатация + - [monitoring.md](30-operations/monitoring.md) — мониторинг и алерты + - [docs.md](30-operations/docs.md) — документирование в gnexus-book +- `90-templates/` — шаблоны + - [new-service-checklist.md](90-templates/new-service-checklist.md) + - [service-doc-template.md](90-templates/service-doc-template.md) + +## Границы + +Этот репозиторий — только правила. Факты (IP, версии, состояние, маршруты) живут +в gnexus-book: https://git.gnexus.space/root/gnexus-book (для агентов — через MCP).