Доработка документации

documentation/ru/docs/architecture/concept.md

@@ -0,0 +1,27 @@
+# Общая архитектура
+
+Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7.
+
+## Схема БД
+Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab.
+
+<figure markdown>
+  ![schema-database.png](img/schema-database.png){ loading=lazy }
+  <figcaption>Схема приложения версия 1.0.0</figcaption>
+</figure>
+
+Важно подчеркнуть, что приложение не сохраняет все бездумно в БД. Во время первого запуска вам будет задан ряд вопросов, ответы на которые повлияют на наполнение БД.
+
+Также приложение старается не хранить лишние данные. Например, если MR был вмержен или закрыт, то нет смысла хранить информацию об этом MR, поэтому при следующем сканировании запись об этом MR, а также обо всех связанных сущностях этого MR (пайплайны, треды...) будут удалены.
+
+## Сканирование GitLab
+Раз в 1 минуту происходит обращение к GitLab API с вашим персональным токеном. Получаемые от GitLab данные сверяются с имеющимися в БД, после чего формируются уведомления, если обнаружены изменения.
+
+!!! question "Почему не использовать Webhook?"
+
+    Не везде имется возможность установить произвольные Webhook. Например, вряд ли кто-то позволит вам установить Webhook из корпоративного GitLab во внешнюю сеть. Переодическое обращение к GitLab API можно выполнять прямо с рабочей машины.
+
+    В будущем планирую добавить поддержку и Webhook.
+
+## Отслеживание репозиториев
+Ключевым (рутовым) элементом являются репозитории.

documentation/ru/docs/getting-started/configuration.md

@@ -1,24 +1,89 @@
-Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4.
+# Первый запуск ассистента
 
-## Создание бота в Telegram
+Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4.
-Перед запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`.
 
 Первым делом вам предложат ввести имя для бота.
 
 ## Конфигурация
-Несмотря на то, какой вариант запуска вы виберете, необходимо будет указать следующие переменные среды:
+Несмотря на то, какой вариант запуска вы вберете, необходимо указать следующие переменные среды:
 
-* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при создании бота.
+* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при [создании бота](creating-telegram-bot.md).
 * `TELEGRAM_BOT_USERNAME` — название, которое вы дали боту. Оканчивается на bot.
-* `GITLAB_PERSONAL_TOKEN` — токен, который вы получили в GitLab
+* `GITLAB_PERSONAL_TOKEN` — токен, который вы [получили в GitLab.](create-gitlab-token.md)
-* `TELEGRAM_PERSON_ID` — ваш id в telegram, можно узнать тут.
+* `TELEGRAM_PERSON_ID` — ваш идентификатор в telegram, можно узнать в боте [@myidbot](@myidbot).
-* `GITLAB_URL` — url на gitlab. Локальный или облачный.
+* `GITLAB_URL` — url на GitLab. Локальный или облачный.
-* `DATASOURCE_URL` — ссылка на базу данных Postgres, в следующем формате: jdbc:postgresql://localhost:5432/gitlab_bot
+* `DATASOURCE_URL` — ссылка на базу данных Postgres, в следующем формате: `jdbc:postgresql://databasehost:5432/gitlab_bot`
 * `DATASOURCE_USERNAME` — пользователь БД
 * `DATASOURCE_PASSWORD` — пароль от БД
 
 ## Запуск Docker Compose
 
+Самый простой способ запустить ассистента, - это docker compose. Создайте файлы `docker-compose.yml` и `.env`. Не забудьте в `.env` указать все необходимые для запуска переменные.
+
+=== ":simple-docker: docker-compose.yml"
+
+    ``` yaml
+    version: '3.8'
+
+    services:
+    
+    gitlab-bot-database:
+        image: postgres:15.1-alpine
+        restart: always
+        hostname: gitlab-bot-database
+        container_name: gitlab-bot-database
+        networks:
+            gitlab-bot:
+        environment:
+            POSTGRES_DB: "gitlab_bot"
+            POSTGRES_USER: "postgres"
+            POSTGRES_PASSWORD: ${DATASOURCE_PASSWORD}
+        volumes:
+            - gitlab-bot-database:/var/lib/postgresql/data/
+    
+    gitlab-bot:
+        image: upagge/gitlab-telegram-notify:latest
+        hostname: gitlab-bot
+        container_name: gitlab-bot
+        networks:
+            gitlab-bot:
+        depends_on:
+            - gitlab-bot-database
+        environment:
+            TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}
+            TELEGRAM_BOT_USERNAME: ${TELEGRAM_BOT_USERNAME}
+            GITLAB_PERSONAL_TOKEN: ${GITLAB_PERSONAL_TOKEN}
+            TELEGRAM_PERSON_ID: ${TELEGRAM_PERSON_ID}
+            GITLAB_URL: ${GITLAB_URL}
+            DATASOURCE_URL: "jdbc:postgresql://gitlab-bot-database:5432/gitlab_bot"
+            DATASOURCE_USERNAME: ${DATASOURCE_USERNAME}
+            DATASOURCE_PASSWORD: ${DATASOURCE_PASSWORD}
+    
+    volumes:
+        gitlab-bot-database:
+    
+    networks:
+        gitlab-bot:
+    ```
+
+=== ":octicons-file-16: .env"
+
+    ``` properties
+    TELEGRAM_BOT_TOKEN=
+    TELEGRAM_BOT_USERNAME=
+    GITLAB_PERSONAL_TOKEN=
+    TELEGRAM_PERSON_ID=
+    GITLAB_URL=
+    DATASOURCE_USERNAME=
+    DATASOURCE_PASSWORD=
+    ```
+
+Теперь запустите композ:
+
+``` shell
+docker compose up -d
+```
+
 ## Запуск Docker
 Команда для запуска выглядит следующим образом:
 

documentation/ru/docs/getting-started/create-gitlab-token.md

@@ -0,0 +1 @@
+# Создание токена GitLab

documentation/ru/docs/getting-started/creating-telegram-bot.md

@@ -0,0 +1,18 @@
+# Регистрируем бота в Telegram
+
+Перед первым запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`.
+
+!!! warning "Имя бота"
+
+    Первые два пункта диалогового меню будет про название бота. Учтите, что это называние общедоступно и случайноы пользователь Telegram сможет найти вашего бота.
+
+    Не переживайте, приложение имеет встроенную защиту от несанкционарованного доступа к боту. Но не смотря на это, ==не рекомендуется использовать в названии бота название организации, или вашу фамилию. Лучше использовать случайное имя.==
+
+После регистрации вам будет выдан токен доступа. Он будет использоваться при запуске ассистента.
+
+Видео процесса:
+<figure>
+    <video width="70%" controls>
+        <source id="mp4" src="../mp4/create-telegram-bot.mp4" type="video/mp4">
+    </videos>
+</figure>

documentation/ru/docs/getting-started/first-start.md

@@ -0,0 +1,5 @@
+# Инициализация бота
+
+<video controls>
+      <source id="mp4" src="../mp4/init-start.mp4" type="video/mp4">
+</videos>

documentation/ru/docs/index.md

@@ -7,10 +7,24 @@ hide:
 ---
 
 # GitLab Notification – Персональный Telegram бот для GitLab
-Персональный ассистент для взаимодействия с GitLab. Получайте уведомления о событиях в GitLab: новые MR, где вы ревьювер, конфликты в ваших MR, уведомления о новых сообщениях в тредах, где вы являетесь участником, и многое другое.
+Персональный ассистент для упрощения работы с GitLab. Получайте персональные уведомления о событиях в GitLab: новый MR на ревью, новый ответ в треде и многое другое.
+
+Бота можно запустить как для облачного GitLab, так и для Self-host решений.
 
 !!! info "GodFather Telegram"
 
     Данный проект использует другой мой проект GodFather Telegram для создания Tlegram ботов различной сложности.
 
-[:material-robot: Создать бота ассистента](getting-started/configuration.md){ .md-button .md-button--primary }
+## Основные возможности
+- Уведомление о появлении нового репозитория.
+- Уведомление о новых MR.
+- Уведомление о возникновении конфликта в MR.
+- Уведомление о смене статуса вашего MR.
+- Уведомление о треде, в которых вас упоминают в формате @nickname.
+- Уведомит о новом треде в вашем MR.
+- Уведомит о закрытии вашего треда в чужом MR.
+- Уведомление о результате сборки.
+
+***
+
+[:material-robot: Создать персонального ассистента](getting-started/configuration.md){ .md-button .md-button--primary }

documentation/ru/docs/privacy.md

@@ -1,5 +1,7 @@
 # :ninja: Конфиденциальность
 
+
+
 Мое решение сфокусировано на приватности и прозрачности. Код и используемые зависимости полностью открыты и доступны для изучения и самостоятельной сборки.
 
 Для работы бота токен доступа устанавливается в переменные среды и никуда не передается, кроме запросов в GitLab.
@@ -7,3 +9,17 @@
 Некоторые уведомления могут содержать чуствительную информацию. Например, уведомления о новых сообщениях в тредах. Возможно вы не захотите раскрывать столько информации о ваших репозиториях Телеграму, ведь через него идет получение уведомлений. Специально для таких случаев предусмотрены уровни конфиденциальности разных типов уведомлений.
 
 Возьмем для примера уведомление о новом сообщении в треде. При минимальном уровне конфиденциальности вы получите уведомление с текстом коментария и сможете сразу ответить на него в телеграм, а при максимальном уровне конфиденциальности будет сообщаться только о факте нового комментария, без содержания. Все это настраивается при первом запуске.
+
+## Несанкционированный доступ
+==Все боты в Telegram являются публичными.== Это значит, что ваш бот может быть найден через поиск в Telegram. Поэтому ==не рекомендуется давать название боту, которое может раскрыть его предназначение.==
+
+Даже если кто-то случайно напишет вашему боту ничего не случится. ==В боте встроена проверка прав доступа.== Вот как она работает:
+
+1. При запуске вы указываете ваш идентификатор в Telegram. В отличие от логина, идентификатор уникален для каждого пользователя и нет возможности его подменить.
+2. Когда бот получает сообщение, он проверяет идентификатор отправителя
+3. Если идентификатор отправителя не совпадает с указанным при запуске, бот не обрабатывает команду
+4. Вы получаете уведомление о том, что такой-то пользователь пытался написать в ваш бот. Вам доступен логин этого пользователя в Telegram, а также текст его сообщения. Это поможет понять является ли попытка доступа злонамеренной и принять меры.
+
+> Уведомления от GitLab всегда отправляются только указанному в конфигурации пользователю.
+
+Демонстрация работы системы защиты:

documentation/ru/docs/stylesheets/extra.css

@@ -4,6 +4,10 @@
     border-left-width: 4px;
 }
 
+.md-typeset .admonition, .md-typeset details {
+    font-size: 0.75rem;
+}
+
 @keyframes heart {
     0%, 40%, 80%, 100% {
         transform: scale(1);

documentation/ru/includes/abbreviations.md

@@ -1 +1,2 @@
 *[MR]: Merge Request
+*[БД]: База данных

documentation/ru/mkdocs.yml

@@ -12,9 +12,12 @@ nav:
     - Уведомления: features/notify.md
     - Быстрые действия: features/interaction-gitlab.md
   - Быстрый старт:
-      - Запуск: getting-started/configuration.md
+      - getting-started/create-gitlab-token.md
-#  - Архитектура:
+      - getting-started/creating-telegram-bot.md
-#      - Концепт: architecture/concept.md
+      - getting-started/configuration.md
+      - getting-started/first-start.md
+  - Архитектура:
+      - Общее: architecture/concept.md
 #  - Блог:
 #      - blog/index.md
   - "Поддержать разработку":
@@ -111,9 +114,9 @@ markdown_extensions:
   - md_in_html
   - footnotes
   - toc:
-      permalink: true
       toc_depth: 3
       title: Содержание
+      permalink: ⚓︎
 
 extra_css:
   - stylesheets/extra.css

documentation/ru/overrides/main.html

@@ -0,0 +1 @@
+{% extends "base.html" %}