# Руководство по развертыванию

Документ описывает требования к окружению и порядок запуска компонентов IOC Checker в рабочей среде.

## Предварительные требования

- Операционная система Linux с доступом к системным сервисам и сетевым ресурсам для обращений к внешним источникам репутации.
- Установленный Python версии 3.10 или выше с возможностью создания изолированного окружения.
- Доступ к менеджеру пакетов pip и средствам сборки зависимостей.
- Возможность устанавливать и запускать системные службы, аналогичные `ioc-checker-api.service` и `ioc-checker-http.service`.
- Доступ к сети для получения токенов провайдеров репутации и загрузки статических ресурсов интерфейса.
- Права на создание каталогов `logs/`, `ui/vendor/` и расположения базы кэша, используемого драйвером SQLAlchemy.
- Доступ к СУБД PostgreSQL или другому хранилищу, указанному в `config.toml`, с правами на создание схемы и обновление последовательностей.

## Подготовка окружения

1. Склонируйте репозиторий в целевую директорию и убедитесь, что у пользователя есть права на запись.
2. Создайте виртуальное окружение Python и активируйте его.
3. Установите зависимости проекта через файл `requirements.txt` либо подходящую сборку под используемую версию Python.
4. Скопируйте `config.toml.example` и `secrets.toml.example` в рабочие файлы конфигурации, задайте параметры подключения к внешним сервисам и учетные данные для источников репутации.
   - В `config.toml` укажите `database_url`, список активных провайдеров в `providers`, таймауты HTTP (`http_timeout`), количество воркеров (`worker_count`) и флаги логирования (`log_level`, `log_file_enabled`).
   - В `secrets.toml` заполните токены провайдеров по именам (`kaspersky`, `top1m`, `abuseipdb`, `otx` и т. д.), при необходимости добавьте ключи с индексами воркеров, если используется параллельное распределение токенов.
5. Выполните скрипт загрузки статических файлов интерфейса `scripts/download_vendor_assets.py`, чтобы подготовить каталоги с локальными ресурсами.
6. Проверьте готовность очереди сообщений и вспомогательных сервисов, если они используются в выбранной конфигурации.
7. Настройте журналы: при необходимости активируйте запись в файл через параметр `log_file_enabled` в `config.toml` и создайте каталог `logs/` с правами на запись.
8. Убедитесь, что каталог для базы кэша доступен для записи, если используется нестандартный путь в `database_url`; при использовании PostgreSQL подготовьте базу данных и проверьте доступ пользователя.
9. При первом запуске выполните загрузку справочника доменных зон `lists/tlds.txt` (входит в репозиторий) и убедитесь в корректности прав на чтение.

## Запуск сервисов

1. Инициализируйте службы API и HTTP-обертки на основе предоставленных unit-файлов системы инициализации, настроив пути до виртуального окружения, рабочей директории и пользователя запуска. HTTP-юнит теперь поднимает полноценный Django-сервер командой `manage.py runserver 0.0.0.0:8000` с `DJANGO_SETTINGS_MODULE=ui_project.settings`, поэтому проверьте доступность порта и корректность переменной окружения.
2. Запустите службы и убедитесь, что они успешно переходят в состояние «active». Для мониторинга используйте системные журналы, встроенный эндпоинт `/api/health` и вывод статуса очереди (`queued_tasks`, `queued_iocs`).
3. При первой установке выполните smoke-тест: отправьте запрос на парсинг текста с несколькими индикаторами и убедитесь, что они проходят очередь и возвращают статусы; затем поставьте тестовое задание через `/api/tasks` и проверяйте его состояние по идентификатору.
4. Проверьте доступность веб-интерфейса и корректную загрузку статических ресурсов из каталога `ui/vendor`; при ошибках убедитесь в наличии скачанных файлов тем и иконок.
5. Настройте резервирование конфигурационных файлов и секретов, а также периодическое обслуживание базы кэша, если используется реляционное хранилище (очистка старых результатов, синхронизация последовательностей).
6. Зафиксируйте расписание обновления токенов провайдеров и контрольных проверок `/api/health` для интеграции с системами мониторинга.

## Обновление и сопровождение

- Перед обновлением фиксируйте текущую версию конфигурационных файлов и резервируйте секреты.
- После обновления зависимостей повторно скачивайте статические ресурсы, если изменились версии используемых библиотек интерфейса.
- Контролируйте журналы API на предмет ошибок постановки задач и времени обработки очереди.
- Регулярно проверяйте актуальность токенов провайдеров и обновляйте их в файле `secrets.toml` по мере истечения срока действия; при смене токена перезапускайте сервисы для применения значений.
- При изменении списка провайдеров в `config.toml` подтверждайте наличие всех обязательных токенов перед запуском воркеров; для временного отключения провайдера удалите его из списка или очистите токен, чтобы избежать ошибок инициализации.
- Для диагностики производительности отслеживайте параметры `worker_count`, `enrichment_concurrency` и `http_timeout`, корректируя их в соответствии с доступными ресурсами и SLA; при росте нагрузки увеличивайте число воркеров и проверяйте наличие достаточного количества токенов.
- Периодически проверяйте целостность базы кэша и актуальность справочника TLD; при миграциях PostgreSQL используйте функции синхронизации последовательностей из `database.py`.
