Initial commit
This commit is contained in:
9
src/dev/deploy.md
Normal file
9
src/dev/deploy.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
icon: material/upload-network
|
||||
---
|
||||
|
||||
# :material-upload-network: Развёртывание и доставка обновлений
|
||||
|
||||
!!! info "TODO"
|
||||
Скоро здесь появится полезная информация.
|
||||
Следи за обновлениями в канале [@iptv_aggregator](https://t.me/iptv_aggregator) или в [репозитории](https://git.axenov.dev/IPTV/docs).
|
||||
97
src/dev/docs.md
Normal file
97
src/dev/docs.md
Normal file
@@ -0,0 +1,97 @@
|
||||
---
|
||||
icon: material/book-cog-outline
|
||||
---
|
||||
|
||||
# :material-book-cog-outline: Сборка документации
|
||||
|
||||
## Стилистика и правила оформления
|
||||
|
||||
Все исходники хранятся в директории `src/` в формате **Markdown** (формат файлов `.md`).
|
||||
|
||||
Структура проекта и его конфигурация описываются в файле `mkdocs.yml` в корне репозитория.
|
||||
|
||||
Структура исходных файлов документации и содержание должны быть согласованными.
|
||||
|
||||
Все ссылки на соседние страницы и изображения должны быть относительными.
|
||||
|
||||
**Каждое предложение должно быть на одной строке.**
|
||||
Это даёт более наглядную разницу (diff) в тексте при работе с git.
|
||||
|
||||
Абзацы и списки должны отделяться 1 пустой строкой сверху и снизу.
|
||||
|
||||
Допустимо использовать любые стилистические возможности темы **Material for MkDocs** и самого **mkdocs**, но не следует визуально перегружать текст.
|
||||
Документацию по ним см. по ссылкам ниже.
|
||||
|
||||
## Добавление изображений
|
||||
|
||||
**Все изображения хранятся только в директории `src/assets/img/` и вложенных в неё.**
|
||||
|
||||
Общая суть такова:
|
||||
|
||||
* чем больше размеры, тем хуже должно быть качество;
|
||||
* чем меньше размеры, тем чётче должен быть текст.
|
||||
|
||||
Каждое изображение должно:
|
||||
|
||||
* быть сохранено в формате jpg;
|
||||
* иметь размер неболее 150 Кб;
|
||||
* быть сжатым с качеством 65-80% от исходного;
|
||||
* быть размером до 1500 px по наибольшей стороне.
|
||||
|
||||
Если на изображении есть текст, он должен оставаться различимым и читаемым.
|
||||
|
||||
Но если на изображении есть любые конфиденциальные данные и его невозможно кадрировать без потери смысла, то их необходимо скрыть.
|
||||
|
||||
Хорошей практикой будет использовать спойлеры для скрытия больших и/или идущих подряд нескольких изображений, например:
|
||||
|
||||
```
|
||||
Совершенно любой текст, lorem ipsum dolor sit amet.
|
||||
Совершенно любой текст, lorem ipsum dolor sit amet.
|
||||
|
||||
??? quote "В этом спойлере несколько больших картинок"
|
||||
|
||||
|
||||
|
||||
Продолжение текста, lorem ipsum dolor sit amet.
|
||||
Продолжение текста, lorem ipsum dolor sit amet.
|
||||
```
|
||||
|
||||
Эти простые правила позволят поддерживать репозиторий достаточно компактным, а страницы делать комфортными для чтения, экономя трафик для мобильных устройств.
|
||||
|
||||
## Стек
|
||||
|
||||
* make
|
||||
* [docker](https://docker.com)
|
||||
* [mkdocs](https://www.mkdocs.org/)
|
||||
* [squidfunk/mkdocs-material](https://hub.docker.com/r/squidfunk/mkdocs-material)
|
||||
* <https://squidfunk.github.io/mkdocs-material>
|
||||
* <https://squidfunk.github.io/mkdocs-material/reference/admonitions/>
|
||||
* <https://squidfunk.github.io/mkdocs-material/reference/icons-emojis/>
|
||||
|
||||
## Запуск mkdocs в контейнере
|
||||
|
||||
```
|
||||
make live
|
||||
```
|
||||
|
||||
Перегенерирует документацию на лету сразу после изменения файлов.
|
||||
|
||||
Открывает [localhost:3000](https://localhost:3000) для просмотра изменений в реальном времени.
|
||||
|
||||
## Генерация статических файлов
|
||||
|
||||
```
|
||||
make build
|
||||
```
|
||||
|
||||
Генерирует статические файлы, которую можно версионировать и хранить/деплоить отдельно.
|
||||
|
||||
Открывает [localhost:8080/docs](https://localhost:8080/docs) для просмотра сгенерированной документации.
|
||||
|
||||
Готовый скомпилированный статический сайт с документацией находится в директории `site/`.
|
||||
Он же хранится в репозитории вместе с исходными файлами, потому что:
|
||||
|
||||
* я посчитал это **более удобным для деплоя**: ради редких обновлений нет смысла тратить ресурсы серверов на ci/cd, actions по хукам и перманентную работу `mkdocs` в режиме `build`;
|
||||
* я посчитал это **более удобным для использования**: можно в любой момент открыть актуальную документацию в браузере через `site/index.html` без необходимости `make` и `docker`.
|
||||
|
||||
Пересборка должна происходить перед каждым коммитом.
|
||||
29
src/dev/index.md
Normal file
29
src/dev/index.md
Normal file
@@ -0,0 +1,29 @@
|
||||
---
|
||||
icon: simple/devbox
|
||||
hide:
|
||||
- toc
|
||||
---
|
||||
|
||||
# :simple-devbox: Для разработчиков
|
||||
|
||||
<div class="grid cards" markdown>
|
||||
- [:material-application-brackets-outline: Среда разработки](local-dev.md)
|
||||
|
||||
---
|
||||
Настройка ПО для работы с кодом проекта
|
||||
|
||||
- [:material-robot-outline: Telegram-бот](tgbot.md)
|
||||
|
||||
---
|
||||
Специфика разработки и отладки Telegram-бота проекта
|
||||
|
||||
- [:material-book-cog-outline: Сборка документации](docs.md)
|
||||
|
||||
---
|
||||
Как скорректировать, проверить и скомплировать эту документацию
|
||||
|
||||
- [:material-upload-network: Развёртывание и доставка обновлений](deploy.md)
|
||||
|
||||
---
|
||||
О том, как опубликовать изменения на сервере
|
||||
</div>
|
||||
9
src/dev/local-dev.md
Normal file
9
src/dev/local-dev.md
Normal file
@@ -0,0 +1,9 @@
|
||||
---
|
||||
icon: material/application-brackets-outline
|
||||
---
|
||||
|
||||
# :material-application-brackets-outline: Среда разработки
|
||||
|
||||
!!! info "TODO"
|
||||
Скоро здесь появится полезная информация.
|
||||
Следи за обновлениями в канале [@iptv_aggregator](https://t.me/iptv_aggregator) или в [репозитории](https://git.axenov.dev/IPTV/docs).
|
||||
80
src/dev/tgbot.md
Normal file
80
src/dev/tgbot.md
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
icon: material/robot-outline
|
||||
---
|
||||
|
||||
# :material-robot-outline: Telegram-бот
|
||||
|
||||
!!! info "Обрати внимание"
|
||||
Локальная среда разработки должна быть [настроена и запущена](local-dev.md).
|
||||
|
||||
## Подготовка бота на стороне Telegram
|
||||
|
||||
1. Написать [@botfather](https://t.me/botfather), создать бота
|
||||
2. Полученный токен установить значением переменной `TG_BOT_TOKEN` в файле `.env` репозитория `web`
|
||||
3. Командой `/mybots` в [@botfather](https://t.me/botfather) выбрать свежесозданного бота, далее `Edit Bot` > `Edit Commands` и отправить текст:
|
||||
```
|
||||
list - Список плейлистов
|
||||
info - Подробности о плейлисте по его коду
|
||||
help - Помощь по командам бота
|
||||
links - Ссылки на все страницы проекта
|
||||
stats - Статистика по плейлистам и каналам
|
||||
```
|
||||
|
||||
## Проброс внешних запросов на локальную машину
|
||||
|
||||
1. Установить [telebit](https://telebit.cloud) и пройти примитивную регистрацию.
|
||||
В результате будет выдан уникальный адрес в формате `https://foo-bar-99.telebit.io`.
|
||||
На email, указанный при регистрации, будет оформлен бесплатный SSL-серификат Let's Encrypt для этого домена.
|
||||
Если адрес не используется месяц+, то сертификат протухнет, но он автоматически восстановится, если адрес начнёт использоваться вновь.
|
||||
|
||||
2. В терминале выполнить:
|
||||
```
|
||||
telebit http 8080
|
||||
```
|
||||
где 8080 -- порт локальной машины, на который проброшен порт 80 из контейнера `iptv-nginx`.
|
||||
Для выключения выполнить:
|
||||
```
|
||||
telebit http
|
||||
```
|
||||
|
||||
3. Проверить работу адреса, перейдя по нему браузером.
|
||||
Должен открыться твой локальный проект.
|
||||
|
||||
4. Полученный адрес установить значением переменной `APP_URL` в файле `.env` репозитория `web`
|
||||
|
||||
5. Установить веб-хук, отправив запрос браузером или любым HTTP-клиентом на адрес:
|
||||
```
|
||||
https://api.telegram.org/bot$BOT_TOKEN/setWebhook?url=$TELEBIT_URL/bot/webhook&secret_token=$SECRET_TOKEN
|
||||
```
|
||||
где:
|
||||
* `$BOT_TOKEN` - авторизационный токен, который @botfather выдал твоему боту;
|
||||
* `$TELEBIT_URL` - адрес, который telebit выдал тебе;
|
||||
* `$SECRET_TOKEN` - секретный токен, опционален, см. ниже.
|
||||
|
||||
6. Проверить веб-хук, отправив запрос браузером или любым HTTP-клиентом на адрес:
|
||||
```
|
||||
https://api.telegram.org/bot$BOT_TOKEN/getWebhookInfo
|
||||
```
|
||||
где:
|
||||
* `$BOT_TOKEN` - авторизационный токен, который @botfather выдал твоему боту.
|
||||
|
||||
7. После разработки нужно установить "боевой" адрес веб-хука аналогично п4.
|
||||
|
||||
## Что за секретный токен?
|
||||
|
||||
Telegram авторизует твоего бота по токену, который выдал ему сам.
|
||||
|
||||
Ты тоже можешь (не) авторизовать Telegram по токену, который ты выдашь ему.
|
||||
|
||||
Для этого нужно в значением переменной `TG_BOT_SECRET` в файле `.env` репозитория `web` установить любую строку.
|
||||
Если ты это сделаешь, тогда ту же строку ты должен передать в параметре `secret_token` метода `setWebhook`.
|
||||
|
||||
В этом случае, все HTTP-запросы, которые приходят от Telegram, будут содержать заголовок `X-Telegram-Bot-Api-Secret-Token` со этой строкой в качестве значения.
|
||||
Эта строка сверяется с той, что указана в `.env` проекта.
|
||||
Если такого заголовка нет или его значение некорректно, входящий запрос отклоняется.
|
||||
|
||||
Если переменная `TG_BOT_SECRET` не задана, то заголовок проверяться не будет.
|
||||
|
||||
См. подробности в документации: [setWebhook](https://core.telegram.org/bots/api#setwebhook)
|
||||
|
||||
|
||||
Reference in New Issue
Block a user