docs: visual guides with platform screenshots (Gitea, ArgoCD, Grafana, Prometheus)

2026-05-28 12:40:41 +03:00
parent e3e438df68
commit 41918487ff
26 changed files with 477 additions and 0 deletions
@@ -99,6 +99,10 @@ export default defineConfig({
            collapsed: false,
            items: [
              { text: 'Обзор', link: '/infrastructure/test-contour/' },
+              { text: 'Визуальные гайды', link: '/infrastructure/test-contour/guides/' },
+              { text: 'Gitea: теги и CI/CD', link: '/infrastructure/test-contour/guides/gitea-ci' },
+              { text: 'ArgoCD: приложения', link: '/infrastructure/test-contour/guides/argocd' },
+              { text: 'Grafana / Prometheus / Loki', link: '/infrastructure/test-contour/guides/monitoring' },
              { text: 'Что сделано + перенос на сервер', link: '/infrastructure/test-contour/test-contour-article' },
              { text: 'Система тегов CI/CD', link: '/infrastructure/test-contour/tags' },
              { text: 'ArgoCD: sova-root и data-test', link: '/infrastructure/test-contour/argocd-apps' }
@@ -13,3 +13,21 @@
  max-width: 100%;
  height: auto;
 }
+
+/* Platform guide screenshots */
+.vp-doc img[src*="/screenshots/"] {
+  display: block;
+  margin: 1rem auto 0.5rem;
+  max-width: 100%;
+  border: 1px solid var(--vp-c-divider);
+  border-radius: 10px;
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.08);
+}
+
+.vp-doc img[src*="/screenshots/"] + em,
+.vp-doc p:has(+ img[src*="/screenshots/"]) {
+  display: block;
+  text-align: center;
+  color: var(--vp-c-text-2);
+  font-size: 0.9em;
+}
@@ -0,0 +1,105 @@
+# ArgoCD: приложения test-контура
+
+ArgoCD — GitOps UI: следит за `sova-deploy` и `sova-mocks`, раскатывает Helm charts в кластер.
+
+Краткая теория: [sova-root и data-test](../argocd-apps).
+
+## 1. Вход
+
+http://argocd.sova.local — логин **admin**, пароль:
+
+```bash
+kubectl -n argocd get secret argocd-initial-admin-secret \
+  -o jsonpath='{.data.password}' | base64 -d && echo
+```
+
+![ArgoCD login](../screenshots/07-argocd-login.png)
+
+## 2. Список Applications
+
+На главной — все приложения test-контура:
+
+| Application | Что деплоит | Есть URL? |
+|-------------|-------------|-----------|
+| `backend-test` | Symfony API | api.test.sova.local |
+| `adminpanel-test` | React admin | admin.test.sova.local |
+| `cabinet-test` | Symfony ЛК | cabinet.test.sova.local |
+| `docs-test` | VitePress docs | docs.sova.local |
+| `mocks-test` | WireMock, Mailpit | internal |
+| `data-test` | PostgreSQL, MySQL, Redis | нет (БД) |
+| `sova-root` | другие Application CR | нет (meta) |
+
+![Applications list](../screenshots/08-argocd-applications.png)
+
+**Sync Status `Unknown`** часто нормален для local — смотрите **Health** и pod'ы в namespace.
+
+## 3. Пользовательское приложение: `backend-test`
+
+Откройте карточку → дерево ресурсов: Deployment, Service, Ingress, CronJob, Secret.
+
+![backend-test detail](../screenshots/09-argocd-backend-test.png)
+
+### Sync вручную
+
+Кнопка **Sync** → **Synchronize** — подтянуть последний `main` из Gitea.
+
+### Terminal в pod (миграции, отладка)
+
+1. Deployment `backend` → Pod  
+2. Container **php-fpm** → иконка **Terminal**  
+3. Пример: `php bin/console cache:clear --env=prod`
+
+Exec включён в `platform/argocd/values-test.yaml` (`exec.enabled: true`).
+
+### CronJob в UI
+
+Фильтр по label `app.kubernetes.io/component: console` — видны `backend-sync-doctors`, `backend-clear-schedule-cache` и т.д.
+
+## 4. `sova-root` — app-of-apps
+
+**Не приложение с URL.** Только создаёт/обновляет другие Application из `argocd/apps/`.
+
+![sova-root](../screenshots/10-argocd-sova-root.png)
+
+«Войти» сюда нельзя — открывайте дочерние apps (`backend-test`, `docs-test`, …).
+
+## 5. `data-test` — слой данных
+
+PostgreSQL (backend + cabinet), MySQL Bitrix, Redis. **Без Ingress.**
+
+![data-test](../screenshots/11-argocd-data-test.png)
+
+Подключение из pod'ов приложений:
+
+```
+postgresql-test.sova-data-test.svc.cluster.local:5432
+mysql-bitrix-test.sova-data-test.svc.cluster.local:3306
+redis-test-master.sova-data-test.svc.cluster.local:6379
+```
+
+Инициализация schema/seed — Job `db-init` (отдельный чарт), не через браузер.
+
+## 6. Типичный цикл после CI
+
+```mermaid
+sequenceDiagram
+  participant Dev as Разработчик
+  participant Gitea as Gitea tag
+  participant CI as Actions
+  participant Deploy as sova-deploy
+  participant Argo as ArgoCD
+  participant K8s as Kubernetes
+
+  Dev->>Gitea: release-test-tag.sh
+  Gitea->>CI: push tag
+  CI->>Deploy: bump values-test.yaml
+  Argo->>Deploy: poll main
+  Argo->>K8s: helm upgrade
+```
+
+1. Push тега в Gitea  
+2. CI обновляет `apps/backend/values-test.yaml`  
+3. ArgoCD auto-sync (или Sync вручную)  
+4. Новый pod с образом из registry  
+
+Дальше: [Grafana, Prometheus, Loki](./monitoring).
@@ -0,0 +1,73 @@
+# Gitea: теги, CI/CD и registry
+
+В test-контуре каждый сервис (`backend`, `adminpanel`, `cabinet`, `docs`) — **отдельный репозиторий** в Gitea. Релиз = **git-тег** → Gitea Actions → Docker-образ → обновление `sova-deploy` → ArgoCD sync.
+
+Подробнее о формате тегов: [Система тегов CI/CD](../tags).
+
+## 1. Вход в Gitea
+
+Откройте http://git.sova.local и войдите под `gitea_admin` (пароль — из bootstrap или `.generated/platform-credentials.env`).
+
+![Страница входа Gitea](../screenshots/01-gitea-login.png)
+
+## 2. Репозитории организации `sova`
+
+Все сервисы и GitOps лежат в org **sova**:
+
+| Репозиторий | Назначение |
+|-------------|------------|
+| `backend`, `adminpanel`, `cabinet`, `docs` | код + `.gitea/workflows/build.yml` |
+| `sova-deploy` | Helm values, ArgoCD manifests |
+| `sova-mocks` | WireMock, Mailpit |
+
+![Организация sova](../screenshots/02-gitea-org-sova.png)
+
+## 3. Gitea Actions — pipeline на push тега
+
+Workflow в каждом app-репозитории:
+
+1. **test** — unit/build проверки  
+2. **build-and-push** — образ в Container Registry  
+3. **deploy-gitops** — commit в `sova-deploy` (`values-test.yaml`)
+
+![Список workflow runs](../screenshots/03-gitea-backend-actions.png)
+
+Откройте последний успешный run — все три job должны быть зелёными:
+
+![Детали pipeline](../screenshots/04-gitea-action-run.png)
+
+::: tip Terminal на runner
+Логи runner: `kubectl logs -n gitea -l app.kubernetes.io/name=actions-runner -c runner -f`
+:::
+
+## 4. Как выкатить тег (с Mac)
+
+```bash
+cd k3s-test
+./scripts/release-test-tag.sh backend   backend-v1.0.1-test
+./scripts/release-test-tag.sh adminpanel adminpanel-v1.0.1-test
+./scripts/release-test-tag.sh cabinet   cabinet-v1.0.1-test
+./scripts/release-test-tag.sh docs      docs-v1.0.1-test
+```
+
+Скрипт создаёт аннотированный тег и пушит в Gitea. Тег виден в репозитории:
+
+![Теги backend](../screenshots/05-gitea-backend-tags.png)
+
+Формат: `{component}-v{semver}-{env}` → например `backend-v1.0.1-test`.
+
+## 5. Container Registry
+
+После успешного `build-and-push` образ появляется в **Packages** репозитория:
+
+![Container packages](../screenshots/06-gitea-backend-packages.png)
+
+В Helm `values-test.yaml` используется pull через `git.sova.local/sova/backend:backend-v1.0.1-test` (см. `./scripts/configure-k3s-registry.sh`).
+
+## 6. Чеклист после релиза
+
+1. http://git.sova.local/sova/backend/actions — все jobs **success**
+2. http://argocd.sova.local — `backend-test` **Synced / Healthy**
+3. `curl http://api.test.sova.local/news/list?page=1` → **200**
+
+Дальше: [ArgoCD — приложения и sync](./argocd).
@@ -0,0 +1,29 @@
+# Визуальные гайды test-контура
+
+Пошаговые инструкции со **скриншотами** реального UI песочницы: Gitea CI, ArgoCD, Grafana, Prometheus и Loki.
+
+Перед просмотром добавьте в `/etc/hosts` IP VM (см. `./scripts/print-urls.sh`):
+
+```
+192.168.252.2 git.sova.local argocd.sova.local grafana.sova.local prometheus.sova.local docs.sova.local
+```
+
+## Разделы
+
+| Гайд | О чём |
+|------|--------|
+| [Gitea: теги и CI/CD](./gitea-ci) | push тега → Actions → registry → deploy-gitops |
+| [ArgoCD: приложения](./argocd) | Applications, sync, backend vs sova-root vs data-test |
+| [Grafana, Prometheus, Loki](./monitoring) | метрики, targets, логи в Explore |
+
+## Обновление скриншотов
+
+Скрины лежат в [`../screenshots/`](../screenshots/). Переснять после изменений UI:
+
+```bash
+cd k3s-test
+./scripts/capture-platform-screenshots/run.sh
+cd sova-docs && npm run build   # локальная проверка
+```
+
+Скрипт использует Playwright и логинится в сервисы test-контура автоматически (креды из `.generated/platform-credentials.env` и kubectl).
@@ -0,0 +1,123 @@
+# Grafana, Prometheus и Loki
+
+В test-контуре мониторинг разделён:
+
+| Инструмент | URL | Задача |
+|------------|-----|--------|
+| **Prometheus** | http://prometheus.sova.local | метрики, targets, PromQL |
+| **Grafana** | http://grafana.sova.local | дашборды + **логи через Loki** |
+| **Loki** | только через Grafana Explore | агрегация логов pod'ов |
+
+Prometheus **не хранит логи** — для логов используйте Grafana → Explore → datasource **Loki**.
+
+Установка Loki/Promtail: `./scripts/deploy-monitoring-logs.sh`
+
+## Grafana
+
+### Вход
+
+http://grafana.sova.local — **admin** / пароль:
+
+```bash
+kubectl -n monitoring get secret kube-prometheus-grafana \
+  -o jsonpath='{.data.admin-password}' | base64 -d && echo
+```
+
+![Grafana login](../screenshots/12-grafana-login.png)
+
+### Главная
+
+Дашборды kube-prometheus (CPU, memory, pod restarts). Полезно для общего health кластера:
+
+![Grafana home](../screenshots/13-grafana-home.png)
+
+### Loki — логи приложений
+
+**Explore** (иконка компаса) → datasource **Loki** → LogQL:
+
+```logql
+{namespace="sova-test"}
+```
+
+Уточнение по pod:
+
+```logql
+{namespace="sova-test", pod=~"backend.*"} |= "error"
+```
+
+![Grafana Explore Loki](../screenshots/14-grafana-loki-explore.png)
+
+::: tip Нет логов?
+1. `./scripts/deploy-monitoring-logs.sh`  
+2. Проверьте Promtail: `kubectl get pods -n monitoring -l app.kubernetes.io/name=promtail`  
+3. В Grafana: Configuration → Data sources → Loki должен быть **green**
+:::
+
+### Типовые сценарии
+
+| Задача | Действие |
+|--------|----------|
+| 500 от API | Loki `{namespace="sova-test", pod=~"backend.*"}` |
+| CronJob упал | `{namespace="sova-test"} \|= "backend-sync-doctors"` |
+| Ingress 502 | `{namespace="ingress-nginx"}` |
+
+## Prometheus
+
+Отдельный UI без логина (test-контур).
+
+### Graph — PromQL запросы
+
+http://prometheus.sova.local/graph
+
+Примеры:
+
+```promql
+up                                    # живые targets
+rate(http_requests_total[5m])         # RPS (если есть метрика)
+container_memory_working_set_bytes{namespace="sova-test"}
+```
+
+![Prometheus Graph](../screenshots/15-prometheus-graph.png)
+
+### Targets — кто отдаёт метрики
+
+http://prometheus.sova.local/targets
+
+**UP** (зелёный) — scrape OK. **DOWN** — проверьте ServiceMonitor / pod.
+
+![Prometheus Targets](../screenshots/16-prometheus-targets.png)
+
+### Быстрая проверка «всё живо»
+
+Запрос `up` за последний час:
+
+![Prometheus up query](../screenshots/17-prometheus-up-query.png)
+
+Значение **1** — target доступен, **0** — проблема.
+
+## Сводка: куда смотреть
+
+```mermaid
+flowchart LR
+  subgraph metrics["Метрики"]
+    prom["Prometheus<br/>prometheus.sova.local"]
+    graf_m["Grafana dashboards"]
+  end
+  subgraph logs["Логи"]
+    loki["Loki"]
+    graf_l["Grafana Explore"]
+    promtail["Promtail"]
+  end
+  pods["Pod logs"] --> promtail --> loki --> graf_l
+  pods --> prom
+  prom --> graf_m
+```
+
+| Симптом | Куда |
+|---------|------|
+| Медленный API, restarts | Grafana dashboards / Prometheus `container_*` |
+| Ошибка в коде, stack trace | Grafana → Loki |
+| ServiceMonitor не работает | Prometheus → Targets |
+| Нет datasource Loki | `./scripts/deploy-monitoring-logs.sh` |
+
+Назад: [Gitea CI/CD](./gitea-ci) · [ArgoCD](./argocd)
@@ -6,6 +6,15 @@

 ## Разделы

+### Визуальные гайды (скриншоты)
+
+- [Обзор гайдов](./guides/) — Gitea, ArgoCD, Grafana, Prometheus, Loki
+- [Gitea: теги и CI/CD](./guides/gitea-ci)
+- [ArgoCD: приложения](./guides/argocd)
+- [Grafana / Prometheus / Loki](./guides/monitoring)
+
+### Текстовая документация
+
 - [Test-контур: что сделано и перенос на сервер](./test-contour-article) — полная статья
 - [Система тегов CI/CD](./tags) — формат тегов и release-скрипт
 - [ArgoCD: sova-root и data-test](./argocd-apps) — зачем эти приложения и почему «нельзя войти»
@@ -0,0 +1,25 @@
+# Platform screenshots (test contour)
+
+Автоматически сгенерировано `./scripts/capture-platform-screenshots/run.sh`.
+
+| File | Title |
+|------|-------|
+| 01-gitea-login.png | Gitea: страница входа |
+| 02-gitea-org-sova.png | Gitea: организация sova |
+| 03-gitea-backend-actions.png | Gitea Actions |
+| 04-gitea-action-run.png | Pipeline run |
+| 05-gitea-backend-tags.png | Теги backend |
+| 06-gitea-backend-packages.png | Container Registry |
+| 07-argocd-login.png | ArgoCD login |
+| 08-argocd-applications.png | Applications list |
+| 09-argocd-backend-test.png | backend-test |
+| 10-argocd-sova-root.png | sova-root |
+| 11-argocd-data-test.png | data-test |
+| 12-grafana-login.png | Grafana login |
+| 13-grafana-home.png | Grafana home |
+| 14-grafana-loki-explore.png | Loki Explore |
+| 15-prometheus-graph.png | Prometheus Graph |
+| 16-prometheus-targets.png | Prometheus Targets |
+| 17-prometheus-up-query.png | PromQL up |
+
+Полный manifest: `manifest.json`
@@ -0,0 +1,91 @@
+{
+  "capturedAt": "2026-05-28T09:37:54.363Z",
+  "vmIp": "192.168.252.2",
+  "items": [
+    {
+      "file": "01-gitea-login.png",
+      "title": "Gitea: страница входа",
+      "notes": ""
+    },
+    {
+      "file": "02-gitea-org-sova.png",
+      "title": "Gitea: организация sova и репозитории",
+      "notes": ""
+    },
+    {
+      "file": "03-gitea-backend-actions.png",
+      "title": "Gitea Actions: workflow backend",
+      "notes": ""
+    },
+    {
+      "file": "04-gitea-action-run.png",
+      "title": "Gitea Actions: прогон pipeline (jobs)",
+      "notes": ""
+    },
+    {
+      "file": "05-gitea-backend-tags.png",
+      "title": "Gitea: теги релиза backend-v*",
+      "notes": ""
+    },
+    {
+      "file": "06-gitea-backend-packages.png",
+      "title": "Gitea: Container Registry (образы)",
+      "notes": ""
+    },
+    {
+      "file": "07-argocd-login.png",
+      "title": "ArgoCD: вход",
+      "notes": ""
+    },
+    {
+      "file": "08-argocd-applications.png",
+      "title": "ArgoCD: список Applications",
+      "notes": ""
+    },
+    {
+      "file": "09-argocd-backend-test.png",
+      "title": "ArgoCD: backend-test (ресурсы и sync)",
+      "notes": ""
+    },
+    {
+      "file": "10-argocd-sova-root.png",
+      "title": "ArgoCD: sova-root (app-of-apps, без pod URL)",
+      "notes": ""
+    },
+    {
+      "file": "11-argocd-data-test.png",
+      "title": "ArgoCD: data-test (PostgreSQL/MySQL/Redis)",
+      "notes": ""
+    },
+    {
+      "file": "12-grafana-login.png",
+      "title": "Grafana: вход",
+      "notes": ""
+    },
+    {
+      "file": "13-grafana-home.png",
+      "title": "Grafana: главная / дашборды",
+      "notes": ""
+    },
+    {
+      "file": "14-grafana-loki-explore.png",
+      "title": "Grafana Explore: логи Loki (namespace sova-test)",
+      "notes": ""
+    },
+    {
+      "file": "15-prometheus-graph.png",
+      "title": "Prometheus: Graph / PromQL",
+      "notes": ""
+    },
+    {
+      "file": "16-prometheus-targets.png",
+      "title": "Prometheus: Status → Targets",
+      "notes": ""
+    },
+    {
+      "file": "17-prometheus-up-query.png",
+      "title": "Prometheus: запрос up (живые targets)",
+      "notes": ""
+    }
+  ]
+}