Руководство по установке и эксплуатации

1. Общие сведения

Настоящее руководство содержит информацию, необходимую для подготовки среды, развертывания, запуска и эксплуатации ПО «Агрегатор новостей», версия 1.0. Программа поставляется правообладателем в виде комплекта Docker Compose для установки на Linux-сервер.

2. Состав программной среды

3. Требования к серверу

Для развертывания требуется Linux-сервер, на котором установлены Docker и Docker Compose, имеется достаточное свободное дисковое пространство для образов, базы данных и рабочих данных программы, а также сетевой доступ к используемым источникам.

Требования к процессору, оперативной памяти и дисковому пространству зависят от количества источников, частоты обработки и объема хранимых данных. В действующей серверной конфигурации используются следующие лимиты оперативной памяти контейнеров: PostgreSQL — 256 МБ, web — 288 МБ, worker — 192 МБ. Эти значения характеризуют действующую конфигурацию и не являются универсальными минимальными требованиями.

4. Получение комплекта поставки

Для установки необходимо получить у ООО «ТЕХ СОЛЮШЕН» комплект поставки версии 1.0. Комплект содержит файлы Docker Compose, исходный код и ресурсы приложения, а также конфигурационные файлы, предусмотренные данной версией поставки.

Секретные значения (пароли, токены, Telegram API Hash, TELEGRAM_SESSION и иные учетные данные) в публичную документацию и комплект поставки с общедоступными значениями не включаются. Они задаются администратором конкретного экземпляра.

5. Подготовка конфигурации

• разместить комплект поставки в отдельном рабочем каталоге на сервере;
• задать параметры подключения к базе данных в конфигурации, входящей в комплект поставки;
• при необходимости изменить HTTP_PORT; значение по умолчанию — 8080;
• если требуется чтение Telegram-каналов, задать Telegram API ID, API Hash и TELEGRAM_SESSION;
• если требуется публикация в Telegram и получение оценок, указать токен Telegram-бота в настройках программы; в поддерживаемой конфигурации может использоваться TELEGRAM_BOT_TOKEN;
• при необходимости использования SOCKS5-прокси для Telegram задать TELEGRAM_PROXY;
• Firecrawl настраивается только при использовании соответствующего опционального сценария.

6. Установка и запуск

Перейти в каталог с комплектом поставки и выполнить:

docker compose up -d --build

Команда формирует предусмотренные поставкой контейнеры и запускает их в фоновом режиме. Использование параметра --build относится к формированию контейнерных образов в рамках Docker-развертывания.

После завершения необходимо убедиться, что контейнеры приложения, базы данных и рабочего процесса запущены. Для просмотра состояния выполнить:

docker compose ps

Для просмотра журналов при диагностике выполнить:

docker compose logs

7. Доступ к веб-интерфейсу

После успешного запуска открыть в браузере адрес http://<адрес-сервера>:8080/ либо адрес с портом, указанным в HTTP_PORT. При использовании внешнего reverse proxy и TLS доступ может предоставляться по HTTPS.

После развертывания программного обеспечения доступ к административному веб-интерфейсу осуществляется с использованием учетных данных администратора, установленных для соответствующего экземпляра программного обеспечения.

8. Эксплуатация

8.1. Подключение источников

В веб-интерфейсе администрирования добавить необходимые RSS/Atom- или HTML-источники. После добавления источника проверить получение материалов и корректность его параметров.

8.2. Фильтрация и дедупликация

Настроить включающие и исключающие ключевые слова. Программа применяет заданные правила отбора, обрабатывает материалы и исключает выявленные дубликаты.

8.3. Очередь

Через веб-интерфейс управлять сформированной очередью и параметрами времени публикации.

8.4. Telegram

Для чтения публичных Telegram-каналов используются Telegram API ID, API Hash и TELEGRAM_SESSION. Для публикации и обработки оценок используется Telegram-бот. Эти функции являются дополнительными и не требуются для работы RSS/HTML-контура.

8.5. Firecrawl

Firecrawl используется опционально для отдельных веб-страниц с динамически формируемым содержимым. Интеграция активируется только при наличии ключа сервиса и включенной настройке.

9. Проверка работоспособности

• веб-интерфейс открывается по настроенному адресу;
• контейнеры приложения, базы данных и рабочего процесса находятся в запущенном состоянии;
• тестовый RSS/Atom- или HTML-источник возвращает материалы;
• настроенные правила фильтрации применяются к полученным материалам;
• материалы отображаются в рабочем процессе/очереди;
• при включенных Telegram-функциях выполняется соответствующий тест получения или публикации.

10. Работа при недоступности внешних интеграций

При недоступности Telegram программа продолжает выполнять базовые функции: веб-администрирование, сбор из RSS/Atom и HTML, фильтрацию, дедупликацию и формирование очереди. Не выполняются только операции, непосредственно связанные с Telegram.

При недоступности Firecrawl не выполняется только опциональная обработка страниц, для которых выбран соответствующий способ получения содержимого; базовый RSS/HTML-контур продолжает работать.

11. Безопасность и резервное копирование

• не размещать в открытом доступе пароли базы данных, Telegram API Hash, TELEGRAM_SESSION, токены ботов и иные секреты;
• ограничивать сетевой доступ к административному интерфейсу средствами инфраструктуры;
• предоставлять административные учетные данные только уполномоченным пользователям;
• выполнять резервное копирование данных в соответствии с регламентом эксплуатации конкретного экземпляра.

12. Остановка и повторный запуск

Для остановки контейнеров без удаления данных использовать:

docker compose stop

Для повторного запуска использовать:

docker compose start

Операции удаления контейнеров, томов или базы данных должны выполняться только администратором с учетом необходимости сохранения пользовательских и служебных данных.

13. Техническая поддержка

Техническое сопровождение и предоставление комплекта поставки осуществляет правообладатель ООО «ТЕХ СОЛЮШЕН». Актуальные контактные данные правообладателя размещаются на сайте правообладателя.