diff --git a/documentation/ru/docs/architecture/concept.md b/documentation/ru/docs/architecture/concept.md index e69de29..56edb59 100644 --- a/documentation/ru/docs/architecture/concept.md +++ b/documentation/ru/docs/architecture/concept.md @@ -0,0 +1,27 @@ +# Общая архитектура + +Поддерживается два режима работы: периодические запуски на ПК и запуск на сервере в режиме 24/7. + +## Схема БД +Приложение имеет БД, которая используется для сохранения состояния отслеживаемых сущностей GitLab. + +
+ ![schema-database.png](img/schema-database.png){ loading=lazy } +
Схема приложения версия 1.0.0
+
+ +Важно подчеркнуть, что приложение не сохраняет все бездумно в БД. Во время первого запуска вам будет задан ряд вопросов, ответы на которые повлияют на наполнение БД. + +Также приложение старается не хранить лишние данные. Например, если MR был вмержен или закрыт, то нет смысла хранить информацию об этом MR, поэтому при следующем сканировании запись об этом MR, а также обо всех связанных сущностях этого MR (пайплайны, треды...) будут удалены. + +## Сканирование GitLab +Раз в 1 минуту происходит обращение к GitLab API с вашим персональным токеном. Получаемые от GitLab данные сверяются с имеющимися в БД, после чего формируются уведомления, если обнаружены изменения. + +!!! question "Почему не использовать Webhook?" + + Не везде имется возможность установить произвольные Webhook. Например, вряд ли кто-то позволит вам установить Webhook из корпоративного GitLab во внешнюю сеть. Переодическое обращение к GitLab API можно выполнять прямо с рабочей машины. + + В будущем планирую добавить поддержку и Webhook. + +## Отслеживание репозиториев +Ключевым (рутовым) элементом являются репозитории. \ No newline at end of file diff --git a/documentation/ru/docs/architecture/img/schema-database.png b/documentation/ru/docs/architecture/img/schema-database.png new file mode 100644 index 0000000..36b6c38 Binary files /dev/null and b/documentation/ru/docs/architecture/img/schema-database.png differ diff --git a/documentation/ru/docs/getting-started/configuration.md b/documentation/ru/docs/getting-started/configuration.md index 491ebe8..6281fbf 100644 --- a/documentation/ru/docs/getting-started/configuration.md +++ b/documentation/ru/docs/getting-started/configuration.md @@ -1,24 +1,89 @@ -Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4. +# Первый запуск ассистента -## Создание бота в Telegram -Перед запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`. +Есть несколько способов запустить бота-помощника. Бот был спроектирован таким образом, чтобы работать локально на вашем ПК, но вы можете запустить его на сервере в режиме 24/4. Первым делом вам предложат ввести имя для бота. ## Конфигурация -Несмотря на то, какой вариант запуска вы виберете, необходимо будет указать следующие переменные среды: +Несмотря на то, какой вариант запуска вы вберете, необходимо указать следующие переменные среды: -* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при создании бота. +* `TELEGRAM_BOT_TOKEN` — токен, который вы получили при [создании бота](creating-telegram-bot.md). * `TELEGRAM_BOT_USERNAME` — название, которое вы дали боту. Оканчивается на bot. -* `GITLAB_PERSONAL_TOKEN` — токен, который вы получили в GitLab -* `TELEGRAM_PERSON_ID` — ваш id в telegram, можно узнать тут. -* `GITLAB_URL` — url на gitlab. Локальный или облачный. -* `DATASOURCE_URL` — ссылка на базу данных Postgres, в следующем формате: jdbc:postgresql://localhost:5432/gitlab_bot +* `GITLAB_PERSONAL_TOKEN` — токен, который вы [получили в GitLab.](create-gitlab-token.md) +* `TELEGRAM_PERSON_ID` — ваш идентификатор в telegram, можно узнать в боте [@myidbot](@myidbot). +* `GITLAB_URL` — url на GitLab. Локальный или облачный. +* `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 Команда для запуска выглядит следующим образом: diff --git a/documentation/ru/docs/getting-started/create-gitlab-token.md b/documentation/ru/docs/getting-started/create-gitlab-token.md new file mode 100644 index 0000000..5dccdb1 --- /dev/null +++ b/documentation/ru/docs/getting-started/create-gitlab-token.md @@ -0,0 +1 @@ +# Создание токена GitLab \ No newline at end of file diff --git a/documentation/ru/docs/getting-started/creating-telegram-bot.md b/documentation/ru/docs/getting-started/creating-telegram-bot.md new file mode 100644 index 0000000..e6f9592 --- /dev/null +++ b/documentation/ru/docs/getting-started/creating-telegram-bot.md @@ -0,0 +1,18 @@ +# Регистрируем бота в Telegram + +Перед первым запуском необходимо создать бота в Telegram. Для этого перейдите в официального бота [@GodFather](https://t.me/BotFather) и выполните команду `/newbot`. + +!!! warning "Имя бота" + + Первые два пункта диалогового меню будет про название бота. Учтите, что это называние общедоступно и случайноы пользователь Telegram сможет найти вашего бота. + + Не переживайте, приложение имеет встроенную защиту от несанкционарованного доступа к боту. Но не смотря на это, ==не рекомендуется использовать в названии бота название организации, или вашу фамилию. Лучше использовать случайное имя.== + +После регистрации вам будет выдан токен доступа. Он будет использоваться при запуске ассистента. + +Видео процесса: +
+
\ No newline at end of file diff --git a/documentation/ru/docs/getting-started/first-start.md b/documentation/ru/docs/getting-started/first-start.md new file mode 100644 index 0000000..466703b --- /dev/null +++ b/documentation/ru/docs/getting-started/first-start.md @@ -0,0 +1,5 @@ +# Инициализация бота + +