Веб-сервис Jinni для работы с документами¶

Jinni – веб-сервис для выполнения операций над документами, такими как распознавание текста в файле и конвертация файла в pdf. Данный сервис может быть развёрнут в операционной системе Windows либо любой другой, поддерживающей среду управления контейнерами Docker. Для более подробной информации обратитесь к Руководству по установке в Docker или документации вашего дистрибутива.

Important

Так как Jinni не требует аутентификации и авторизации при обработке запросов, он должен быть доступен только с серверов приложений, на которых расположены экземпляры веб-сервиса TESSA и сервисы Chronos. Настройка ограничения доступа должна осуществляться внешними средствами: межсетевыми экранами, настройками веб-сервера и т.п. Далее приводится инструкция без дополнительных настроек ограничений доступа к веб-сервису Jinni.

Установка Jinni в среде Docker¶

Подготовка к установке¶

Перед выполнением дальнейших действий необходимо выполнить шаги для установки и настройки компонента docker. Для более детальной информации обратитесь к инструкции по Docker на сайте https://docs.docker.com/ или вашего дистрибутива операционной системы.

Tip

При установке Jinni потребуется доступ к репозиторию Docker Hub для загрузки образа с операционной системой и всеми необходимыми зависимостями. Если на сервере, где выполняется установка, отсутствует доступ к репозиторию, то обратитесь к разделу Экспорт и импорт локального Docker-образа.

Откройте папку с основной сборкой TESSA и перейдите в папку Docker\jinni.

Если установка выполняется в Linux, то выполните инициализацию прав для запуска скриптов:

chmod 755 build.sh run.sh start.sh stop.sh

Создайте папку lic и разместите в ней файл с лицензией с расширением .jlic или .tlic. Вы можете использовать другую папку, в которой будет размещен лицензионный файл. Учтите это при запуске run-скрипта.

Note

Проверьте и при необходимости измените конфигурационные параметры веб-сервиса перед установкой. Подробнее см. Конфигурирование веб-сервиса.

Создание и сборка образа¶

Для создания Docker-образа выполните скрипт build.bat (для Windows) или build.sh (для Linux).

При выполнении скрипта можно согласиться с предложенными значениями по умолчанию или задать необходимые значения параметров:

Image name - имя образа в среде Docker. По умолчанию значение jinni. Вы можете изменить его на другое уникальное имя.

Note

Если планируется создавать несколько образов в одной среде Docker, то рекомендуется называть их в зависимости от конфигурации. Например, jinni-full - для образа с поддержкой всех операций, jinni-ocr - для образа с поддержкой только операций распознавания текста, jinni-convert - для образа с поддержкой операции конвертации файла и т.д.
Service path - путь к папке с веб-сервисом Jinni. Если установка выполняется не из основной сборки, то необходимо указать абсолютный или относительный путь до папки с веб-сервисом Jinni, который собран под Linux. По умолчанию этот путь соответствует linux\jinni.

Создание и запуск контейнера¶

Для создания и запуска Docker-контейнера выполните скрипт run.bat (для Windows) или run.sh (для Linux).

При выполнении скрипта можно согласиться с предложенными значениями по умолчанию или задать необходимые значения параметров:

Image name - имя образа, который был ранее создан в среде Docker build-скриптом. По умолчанию значение jinni.
Container name - имя контейнера, который будет создан и запущен в среде Docker на основе образа Image name. По умолчанию значение jinni. Вы можете изменить его на другое уникальное имя.

Note

Для одного образа может быть запущено несколько контейнеров со своими наборами параметров. При этом контейнеры должны иметь уникальные имена и публичные конечные точки.
License folder path - путь к папке с файлом лицензии, которая будет смонтирована в контейнер. По умолчанию этот путь соответствует Docker\jinni\lic в основной сборке TESSA. Вы можете изменить значение на другой путь к папке.

Note

Если хост работает на ОС Windows, то при использовании относительного пути к папке указывайте в начале .\. Например, .\..\..\share\folder.
Public port number - номер порта, по которому контейнер с веб-сервисом Jinni будет доступен с хоста, а также из других компонентов.
Public endpoint address - публичная конечная точка, по которой выполняется обращение к веб-сервису Jinni внутри Docker-контейнера. Используется совместно с параметром Public port number - порт, заданный в публичной конечной точке, должен совпадать с портом из параметра Public port number.
Redis IP address - адрес, по которому доступен Redis для обращения из Docker-контейнера. По умолчанию используется значение host-gateway - переменная среды Docker, содержащая IP-адрес хоста, который используется как шлюз (gateway) для связи с внешней сетью или другими контейнерами в той же сети.

Note

Данное значение будет использоваться внутри Docker-контейнера для подключения к Redis по псевдониму, заданному в конфигурационном файле app-ext.json. Если Redis установлен не на хост-машине, то измените значение IP-адреса на подходящее. Также предполагается, что Redis прослушивает стандартный порт (6379). Если это не так, то обратитесь к разделу ‘Конфигурирование веб-сервиса’ и выполните ручную настройку.

Запуск и остановка контейнера¶

Для остановки и последующего запуска существующего контейнера используйте скрипты stop.bat и start.bat (для Windows) или stop.sh и start.sh (для Linux).

Проверка работоспособности веб-сервиса¶

На хост-машине или из любого другого компонента системы (например, Chronos или веб-сервис TESSA) выполните запрос по адресу http://localhost:19735/check.

Tip

Замените http://localhost:19735 на адрес веб-сервиса Jinni, который был задан при запуске.

Можете использовать веб-браузер или выполнить команду в консоли, если установка выполняется в Linux без GUI:

curl http://localhost:19735/check

Будет отображено содержимое страницы примерно следующего вида. Если на странице не заметно ошибок, то веб-сервис корректно настроен.

Для проверки доступности компонента через механизм мониторинга выполните команду PrintDiscoveryInfo с помощью консольной утилиты tadmin:

tadmin PrintDiscoveryInfo -q

которая отображает все доступные компоненты

OK jinni (great-monkey-LwNirD) last seen <1min

Установка Jinni в Windows¶

Подготовка к установке¶

Если веб-сервис должен поддерживать операции по конвертации файлов, то предварительно необходимо выполнить следующие действия:

Для конвертации офисных файлов в pdf необходимо установить и настроить офисный пакет LibreOffice или OpenOffice (для 64-битной системы должна быть установлена 64-битная версия офисного пакета LibreOffice/OpenOffice).
Для конвертации html файлов в pdf необходимо установить и настроить конвертер wkhtmltopdf.

Note

По умолчанию в веб-сервисе уже заданы настройки для конвертации файлов с помощью LibreOffice и WkHtmlToPdf. Если у вас возникли проблемы с конвертацией, проверьте параметры "OpenOfficePython" и "WkHtmlToPdf" в конфигурационном файле веб-сервиса app-ext.json и укажите корректные значения.

Укажите путь до файла с лицензией *.jlic или *.tlic в параметре "LicenseFile" конфигурационного файла app.json.

Note

Проверьте и при необходимости измените конфигурационные параметры веб-сервиса перед установкой. Подробнее см. Конфигурирование веб-сервиса.

Запуск веб-сервиса из исполняемого файла¶

Откройте папку с основной сборкой TESSA и перейдите в папку Services\jinni.

Для запуска веб-сервиса выполните скрипт start.bat.

При выполнении скрипта можно согласиться с предложенными значениями по умолчанию (тогда веб-сервис будет поддерживать все возможные виды операций) или задать необходимые значения параметров:

Support text recognition - включает (значение TRUE - по умолчанию) или отключает (значение FALSE) поддержку операций по распознаванию текста в файле.
Support file conversion - включает (значение TRUE - по умолчанию) или отключает (значение FALSE) поддержку операций по конвертации файла в pdf.
Public endpoint address - конечная точка, по которой выполняется обращение к веб-сервису Jinni из других компонентов системы.
Listen endpoint addresses - набор прослушиваемых конечных точек, перечисленных через пробел, по которым выполняется обращение к веб-сервису Jinni. Обычно, совпадает с Public endpoint address. Подробнее см. Изменение прослушиваемых конечных точек Jinni.

Запуск веб-сервиса посредством IIS¶

Выполните предварительные настройки и создание учётной записи, если эти действия не были выполнены ранее.

При настройке компонентов также включите компонент Инициализация приложений в группе Службы IIS → Службы интернета → Компоненты разработки приложений.

Модуль инициализации приложений позволяет IIS упреждающе выполнять задачи инициализации, такие как выполнение первоначального HTTP-запроса к приложению или вызов пользовательской логики для выполнения действий, необходимых для “разогрева” приложения.

В Диспетчер служб IIS создайте новый пул приложений jinni и укажите версию среды CRL .NET равную Без управляемого кода.

В качестве учётной записи укажите “tessa”. Для настройки учётной записи необходимо выбрать созданный в предыдущем пункте пул приложений и нажать Дополнительные параметры…:

В открывшемся окне в поле Удостоверение нажать на кнопку с изображением трех точек:

Выбрать Особая учетная запись, нажав на кнопку Установить… откроется окно, где необходимо указать учетную запись (в формате имя домена\имя учетной записи и пароль):

Important

Убедитесь, что для параметра Максимальное число рабочих процессов установлено значение 1 (по умолчанию).

Параметр Режим запуска должен быть равен значению Всегда запущен / AlwaysRunning.

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

Для параметра Тайм-аут простоя (в минутах) укажите значение 0.

Тайм-аут простоя равный 0 означает, что время ожидания приложения никогда не истекает. IIS не уничтожит приложение, даже если оно не получало ни одного HTTP-запроса в течение неопределенного времени.

Убедитесь, что веб-сайт Default Web Site запущен (щелкаем правой кнопкой на сайте, далее Управление веб-сайтом → Запустить).

Создайте директорию C:\inetpub\wwwroot\tessa\jinni, если она не была создана ранее. Скопируйте в неё содержимое папки Services\jinni, которая находится в папке с основной сборкой TESSA.

Далее в диспетчере IIS вы увидите Default Web Site и вложенную в него папку tessa\jinni. Папку необходимо преобразовать в приложение через контекстное меню.

В открывшемся окне для параметра Пул приложений укажите значение jinni.

С помощью того же контекстного меню на приложении jinni выберите пункт Управление приложением → Дополнительные параметры.

В открывшемся окне для параметра Предварительная установка включена установите значение True.

На уровне папки tessa в разделе Параметры SSL включите флажок Требовать SSL, сертификаты клиента: игнорировать.

Затем на уровне приложения jinni в разделе Проверка подлинности включите Анонимная проверка подлинности, а все остальные отключите.

Настройте переменные окружения веб-сервиса в файле jinni\web.config. В файле уже заданы переменные, которые используются по умолчанию. Измените их, если требуется.

<environmentVariables>
  <environmentVariable name="JINNI_REDIS" value="" />
  <environmentVariable name="JINNI_SERVER_CODE" value="" />
  <environmentVariable name="JINNI_LISTEN" value="" />
  <environmentVariable name="JINNI_ENDPOINT" value="http://localhost/tessa/jinni" />
  <environmentVariable name="JINNI_SUPPORT_OCR" value="true" />
  <environmentVariable name="JINNI_SUPPORT_CONVERT" value="true" />
</environmentVariables>

В качестве альтернативного варианта установки переменных окружения можно воспользоваться диспетчером служб IIS. Для этого на уровне приложения jinni в разделе Редактирование конфигураций нужно выбрать параметр system.webbServer/aspNetCore. В поле environmentVariables нажать на кнопку с изображением трех точек:

В открывшемся окне установите необходимые значения для переменных окружения.

После изменения переменных окружения нажмите на кнопку Применить в разделе Редактирование конфигураций.

Перезапустите пул приложений jinni.

Проверка работоспособности веб-сервиса¶

На машине, где установлен веб-сервис, или из любого другого компонента системы (например, Chronos или веб-сервис TESSA) выполните запрос по адресу http://localhost:19735/check.

Note

Замените http://localhost:19735 на адрес веб-сервиса Jinni, который был задан при запуске.

Будет отображено содержимое страницы примерно следующего вида. Если на странице не заметно ошибок, то веб-сервис корректно настроен.

Для проверки доступности компонента через механизм мониторинга выполните команду PrintDiscoveryInfo с помощью консольной утилиты tadmin:

tadmin PrintDiscoveryInfo -q

которая отображает все доступные компоненты

OK jinni (slim-football-RcVphk) last seen <1min

Конфигурирование веб-сервиса¶

Конфигурирование веб-сервиса Jinni выполняется посредством установки переменных окружения.

Для включения или выключения поддерживаемых операций веб-сервисом Jinni, а также установки прослушиваемой конечной точки необходимо выполнить установку переменных окружения:

JINNI_SUPPORT_OCR - включает (значение TRUE) или отключает (значение FALSE) поддержку операций по распознаванию текста в файле.
JINNI_SUPPORT_CONVERT - включает (значение TRUE) или отключает (значение FALSE) поддержку операций по конвертации файла в pdf.
JINNI_ENDPOINT - публичная конечная точка, по которой выполняется обращение к веб-сервису Jinni из других компонентов системы.
JINNI_LISTEN - набор прослушиваемых конечных точек, перечисленных через пробел, по которым выполняется обращение к веб-сервису Jinni. Подробнее см. Изменение прослушиваемых конечных точек Jinni.
JINNI_REDIS - набор строк подключения к Redis, перечисленных через запятую без пробела. Если в составе строки подключения содержатся запятые, то её нужно поместить в одинарные ("complex, connection, string") или двойные кавычки ("complex, connection, string"). По умолчанию значение пусто и используются параметры из конфигурации (см. app.json и app-ext.json).
JINNI_SERVER_CODE - сервер коды для каждого из подключений, перечисленных через запятую без пробела. По умолчанию значение пусто и используются параметры из конфигурации (см. app.json и app-ext.json).
!!! important Если указан один код сервера, то он будет использоваться для всех строк подключения к Redis. Если указан массив сервер кодов, то количество элементов в нём должно совпадать.

Все переменные окружения, кроме JINNI_LISTEN могут быть переопределены с помощью аргументов командной строки при запуске веб-сервиса Jinni.

Например запись:

jinni -endpoint:http://localhost:5124 -support_ocr:true -redis:redis1,redis2

эквивалентна установке переменных окружения JINNI_ENDPOINT, JINNI_SUPPORT_OCR, JINNI_REDIS.

Конфигурирование `Dockerfile`¶

Tip

По умолчанию веб-сервис сконфигурирован для работы со всеми поддерживаемыми операциями. Если заданная по умолчанию конфигурация не требует изменений, то пропустите дальнейшие действия по генерации Dockerfile.

Tip

Для работы генератора требуется наличие установленного интерпретатора Python и установленного пакета Jinja.

Откройте папку с основной сборкой TESSA, перейдите в папку Docker\jinni и запустите скрипт docker-generator.py, который предназначен для генерации Dockerfile, включающего только необходимый набор ПО.

Синтаксис запуска скрипта генерации Dockerfile:

python ./docker-generator.py --infile Dockerfile.template --outfile ./Dockerfile [--ocr] [--convert] [--hconvert]

Описание обязательных параметров скрипта:

--infile - путь к основному файлу шаблона, расположенному в папке templates.
--outfile - путь к выходному сгенерированному файлу Dockerfile.

Описание необязательных параметров скрипта:

--ocr - добавляет поддержку операций по распознаванию текста в файле.
--convert - добавляет поддержку операций по конвертации файла в pdf.
--hconvert - добавляет поддержку операций по конвертации html-файла в pdf.

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

Note

В сгенерированный файл Dockerfile будут добавлены команды для установки необходимых пакетов и репозиториев, в зависимости от указанных параметров конфигурации контейнера. Также будут установлены соответствующие переменные окружения среды контейнера, которые используются веб-сервисом.

Tip

Оба параметра --convert и --hconvert устанавливают переменную среды, которая отвечает за поддержку операций по конвертации файла. Для включения или отключения конвертации файлов определённых форматов (офисных или html) измените конфигурационные параметры "OpenOfficePython" и "WkHtmlToPdf" в конфигурационном файле веб-сервиса app.json перед созданием Docker-образа на основе Dockerfile.

Конфигурационные параметры `app.json`¶

Параметр:
```
"Redis": [ "localhost" ],
"ServerCode": "platform"
```
Набор строк подключения к серверам Redis, в простом случае - одно значение в виде адреса сервера, который будет использован для механизма автодискавери и мониторинга. В качестве допустимых адресов возможно указать localhost, IP-адрес или DNS-имя серверов Redis, и опционально номер порта после двоеточия: 127.0.0.1:6379 (6379 - порт по умолчанию). Если один веб-сервис планируется использовать для нескольких стендов, а для каждого стенда настроен свой Redis, то в качестве значения ключа "Redis" необходимо указать набор адресов к каждому серверу Redis. Более подробную информацию см. Настройка Redis.
Параметр:
```
"ServerCode": "platform"
```
Набор сервер кодов, используемых для проверки инициализированности данных в Redis. Может быть строкой, если для всех подключений к Redis используется один и тот же сервер код. Если задан как массив строк, то количество его элементов должно совпадать с количеством строк подключения к Redis.
Параметр:
```
"LicenseFile": "@*.?lic"
```
Ссылка на присланный вам файл лицензии. По умолчанию используется файл с расширением .jlic или .tlic в папке рядом с конфигурационным файлом, поэтому достаточно скопировать файл лицензии в эту папку. Если файл лицензии должен лежать в другой папке, то путь к нему вы можете записать в этом параметре. Если файл лежит рядом с файлом app.json, то перед именем файла необходимо поставить @.
Параметр:
```
"ServerDependencies": "Tessa.Server.TessaServerDependencies, Tessa.Server"
```
Полное имя типа с указанием имени сборки, который реализует интерфейс ITessaServerDependencies для определения дополнительных зависимостей для использования в расширениях. Оставьте значение по умолчанию, кроме случаев, когда вы реализуете собственный класс, реализующий указанный интерфейс.
Параметр:
```
"HealthCheckIsEnabled": true
```
Признак того, что доступна проверка здоровья веб-сервиса по адресу /check (например, http://localhost:19735/check). При переходе по такому адресу выводится подробная информация по серверу (включая операционную систему и версию .NET), а также подключенным компонентам и типам поддерживаемых операций. Для production-установки рекомендуется указать false для повышения безопасности. Независимо от значения, указанного для этой настройки, по адресу /hcheck возможна быстрая проверка работоспособности веб-сервиса, в т.ч. возможность принимать HTTP-запросы, при этом возвращается только состояние “здоров/не здоров”, что не влияет на безопасность.
Параметр:
```
"SwaggerDocIsEnabled": true
```
Признак того, что доступна автоматическая документация по всем доступным HTTP-методам (в т.ч. REST) по адресу /swagger (например, http://localhost:19735/swagger). Для production-установки рекомендуется указать false для повышения безопасности.
Параметр:
```
"SecureServerStackTrace": false
```
Признак запрета передачи стек-трейса вызывающей стороне из веб-сервиса. По умолчанию false, т.е. передача разрешена. Установите true, чтобы стек-трейсы исключений не передавались с веб-сервиса на клиент.
Параметр:
```
"Discovery.MonitorIntegrationEnabled": false,
```
Признак того, что включена интеграция с Tessa.Monitor. Укажите true, если необходимо включить интеграцию.
Параметр:
```
"Discovery.MonitorPort": 5100
```
Порт для подключения к сервису Tessa.Monitor, который используется для мониторинга нагрузки. Используется, если включена интеграция в параметре Discovery.MonitorIntegrationEnabled.
Параметр:
```
"LimitMaxThreads": true
```
Признак того, что максимальное число потоков для каждой параллельной операции, такой как конвертация файла, ограничивается до безопасного значения. Указание true (рекомендуется) резервирует одно ядро при таких операциях, обеспечивая стабильное время реакции на другие запросы, пока выполняется длительная параллельная операция.
Параметр:
```
"MultipartBodyLengthLimit": -1
```
Максимальный размер длины каждого составного тела. Разделы форм, превышающие это ограничение, при анализе будут вызывать исключение. По умолчанию размер тела неограничен.
Параметр (группа Operations):
```
"QueueSize": 1000
```
Максимальный размер очереди обрабатываемых фоновых операций. Если количество элементов превышает максимально допустимое, то дальнейшие попытки добавления элементов будут блокированы до тех пор, пока число элементов не сократиться до допустимого значения. Это может привести к тому, что некоторые операции добавления элементов будут заблокированы, и поток, выполняющий эти операции, будет приостановлен до тех пор, пока не освободится место в очереди.
Параметр (группа Operations):
```
"RestoreQueue": false
```
Признак того, что при запуске веб-сервиса необходимо выполнять попытку восстановления очереди операций с учётом их статуса. Если на момент запуска веб-сервиса какая-либо из операций находилась в процессе обработки, то она будет повторно взята в работу при условии, что не превышено максимальное количество попыток выполнения операции "ExecutionAttempts". По умолчанию значение false - восстановление отключено.
Параметр (группа Operations):
```
"ExecutionAttempts": 1
```
Максимальное количество попыток выполнения операции, при достижении которого операция не будет обрабатываться повторно. Параметр учитывается только при восстановлении очереди веб-сервиса (параметр "RestoreQueue" имеет значение true). По умолчанию значение 1.

Note

При каждом запуске обработки операции количество попыток выполнения операции увеличивается на 1.
Параметр (группа Operations):
```
"ExecutionTimeout": "0.01:00:00"
```
Тайм-аут выполнения фоновой операции. Если операция выполняется дольше заданного времени, то она будет отменена. По умолчанию 1 час.
Параметр (группа Operations):
```
"CancellationAttempts": 60
```
Количество попыток отмены фоновой операции, обрабатываемой веб-сервисом. Устанавливается в паре с параметром CancellationDelay. По умолчанию 60 раз.
Параметр (группа Operations):
```
"CancellationDelay": 1000
```
Задержка в миллисекундах между попытками отмены фоновой операции, обрабатываемой веб-сервисом. Устанавливается в паре с параметром CancellationAttempts. По умолчанию 1000 миллисекунд. Итоговое время ожидания отмены операции будет равно CancellationDelay * CancellationAttempts.
Параметр (группа Operations):
```
"DataStoragePeriod": "1.00:00:00"
```
Срок хранения данных фоновой операции, по истечении которого операция считывается устаревшей. По умолчанию 1 день.
Параметр (группа Operations):
```
"DataCollectorInterval": "0.01:00:00"
```
Интервал работы фонового сервиса по удалению данных, связанных с устаревшей фоновой операцией. По умолчанию запуск каждый час.
Параметр (группа FileConverter):
```
"WkHtmlToPdf": "wkhtmltopdf"
```
Путь до программы wkhtmltopdf, которая будет использоваться для конвертации html файлов в pdf. Для отключения конвертации файлов в формате html укажите пустую строку "".
Параметр (группа FileConverter):
```
"OpenOfficePython": "python3"
```
Путь к файлу python (интерпретатору языка Python), который расположен внутри папки с установленным LibreOffice/OpenOffice. По умолчанию в конфигурационном файле прописан путь для LibreOffice. Для отключения конвертации файлов офисных форматов укажите пустую строку "".
Параметр (группа FileConverter):
```
"UnoconvExternalCommand": null
```
Путь к внешнему исполняемому файлу “unoconv”, который будет использоваться вместо встроенного скрипта “unoconv” для конвертации документов в LibreOffice/OpenOffice.
Параметр (группа FileConverter):
```
"MaintenancePeriod": "0.01:00:00"
```
Частота технического обслуживания фонового сервиса для конвертации (перезапуск LibreOffice/OpenOffice). По умолчанию запуск каждый час.

Конфигурационные параметры `app-ext.json` для Windows¶

Параметр (группа FileConverter):
```
"WkHtmlToPdf": "%ProgramFiles%\\wkhtmltopdf\\bin\\wkhtmltopdf.exe"
```
Путь до программы wkhtmltopdf, которая будет использоваться для конвертации html файлов в pdf. Для отключения конвертации файлов в формате html укажите пустую строку "".
Параметр (группа FileConverter):
```
"OpenOfficePython": "%ProgramFiles%\\LibreOffice\\program\\python.exe"
```
Путь к файлу python.exe (интерпретатору языка Python), который расположен внутри папки с установленным LibreOffice/OpenOffice. По умолчанию в конфигурационном файле прописан путь для LibreOffice. Для отключения конвертации файлов офисных форматов укажите пустую строку "".

Конфигурационные параметры `app-ext.json` для Docker¶

Параметр:
```
"Redis!!": [ "redis" ]
```
Набор строк подключения к серверам Redis. Более подробно см. в app.json.
Параметр:
```
"LicenseFile": "/var/lic/*.?lic"
```
Ссылка на присланный вам файл лицензии. По умолчанию используется файл с расширением .jlic или .tlic в папке /var/lic, поэтому достаточно скопировать файл лицензии в эту папку. Если файл лицензии должен лежать в другой папке, то путь к нему вы можете записать в этом параметре. Если файл лежит рядом с файлом app-ext.json, то перед именем файла необходимо поставить @.

Часто решаемые задачи¶

Использование одного экземпляра Jinni для разных инсталляций системы¶

Веб-сервис Jinni может быть сконфигурирован для работы одновременно с несколькими инсталляциями/контурами системы.

Tip

Убедитесь, что веб-сервис Jinni доступен со всех серверов приложений, на которых расположены экземпляры веб-сервиса TESSA и сервисы Chronos, по указанной при конфигурировании и запуске публичной конечной точке.

Если установка выполняется в ОС Windows, то достаточно указать в конфигурационном файле app.json адреса всех экземпляров Redis, которые связаны с необходимыми инсталляциями/контурами системы. Например:

"Redis": [ "redis1", "redis2" ]

Если установка выполняется в среде Docker, то необходимо изменить скрипты запуска контейнера run.bat (для Windows) или run.sh (для Linux), добавив параметры для маппинга адресов Redis и их псевдонимов. Для этого задайте нужные значения для параметров --add-host. Например:

--add-host=redis1:192.168.0.1 \
--add-host=redis2:192.168.0.2 \

где

192.168.0.x - адреса, по которым доступны Redis для обращения из Docker-контейнера.

Note

Если хост-машина работает на ОС Windows, то переносы строк в скриптах должны задаваться с помощью карета (^), а не обратного слэша (\).

Теперь возможны несколько сценариев конфигурирования параметров для подключения к Redis.

Использование монтируемого конфигурационного файла¶

На хосте в папке Docker\jinni\config основой сборки TESSA в конфигурационном файле app-ext.json укажите адреса всех экземпляров Redis, которые связаны с необходимыми инсталляциями/контурами системы. Например:

"Redis!!": [ "redis1", "redis2" ]

Перезапустите контейнер и проверьте подключение к Redis.

!!! tip
    Если потребуется запустить на одном образе более одного контейнера с разным набором настроек подключения к Redis, то достаточно создать новый конфигурационный файл по аналогии с [app-ext.json](#jinni-configuration-file-extended-docker) с необходимыми параметрами, разместить его в монтируемой папке и указать к ней путь при выполнении `run`-скрипта.

Использование переменной окружения¶

Измените run-скрипт, добавив в него переменную окружения для установки псевдонима строки подключения к Redis:

--env JINNI_REDIS=redis1,redis2 \

Обратитесь к разделу Создание и запуск контейнера с учётом изменённой конфигурации.

Распределение нагрузки с помощью нескольких экземпляров Jinni¶

Вы можете запустить несколько экземпляров веб-сервиса Jinni для распределения нагрузки. В таком случае при создании запросов к веб-сервису на обработку операций будет учитываться текущий размер очереди операций на веб-сервисах. Запрос будет отправляться на тот веб-сервис, где размер очереди наименьший.

Если требуется запустить несколько контейнеров веб-сервиса Jinni в среде Docker на базе разных образов (если необходимо по-разному сконфигурировать веб-сервис), то обратитесь к разделам Создание и сборка образа и Создание и запуск контейнера. Учтите, что названия создаваемых образов, запускаемых контейнеров, значения публичных портов и конечных точек должны быть уникальными.

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

Для запуска нескольких экземпляров веб-сервиса Jinni в Windows обратитесь к разделам:

Запуск веб-сервиса из исполняемого файла - при запуске укажите необходимую конфигурацию и уникальный публичный порт, публичную конечную точку и прослушиваемые конечные точки.
Запуск веб-сервиса посредством IIS - при запуске добавьте новый пул приложений, создайте копию папки C:\inetpub\wwwroot\tessa\jinni с уникальным именем и настройте приложение, как описано в инструкции.

Изменение прослушиваемых конечных точек Jinni¶

По умолчанию в качестве прослушиваемой конечной точки веб-сервисом Jinni используется http://*:5000. Прослушиваемые конечные точки могут отличаться от публичной конечной точки, по которой веб-сервис доступен из других компонентов системы.

Изменение прослушиваемой конечной точки с помощью аргументов командной строки в Dockerfile¶

Для изменения прослушиваемой конечной точки следует модифицировать Dockerfile, указав необходимые значения в параметрах EXPOSE и CMD перед созданием Docker-образа с помощью build-скрипта. Например:

EXPOSE 5124
CMD [ "./Jinni", "http://*:5124" ]

Если в run-скрипте порт будет использоваться для маппинга, то измените его тоже. Например:

-p $PublicPort:5124 \

Изменение прослушиваемой конечной точки с помощью переменной окружения в Docker¶

Измените run-скрипт, добавив в него переменную окружения JINNI_LISTEN значением для которой являются прослушиваемые конечные точки, перечисленные через пробел. Например:

--env JINNI_LISTEN=http://*:5124 \

Убедитесь, что порт для изменённой прослушиваемой конечной точки указан в Dockerfile в инструкции EXPOSE и в теле run-скрипта при маппинге портов (по умолчанию 5000).

Изменение прослушиваемой конечной точки при запуске веб-сервиса в Windows¶

Если веб-сервис запускается с помощью исполняемого файла, то для изменения прослушиваемой конечной точки укажите необходимое значение для переменной JINNI_LISTEN при запуске скрипта start.bat, который находится рядом с запускаемым исполняемым файлом Jinni.exe.

Если веб-сервис запускается в IIS, то измените переменную JINNI_LISTEN в файле web.config или с помощью редактора конфигурации в диспетчере служб IIS и перезапустите пул приложений.

Экспорт и импорт локального Docker-образа¶

Если при установке веб-сервиса Jinni в среде Docker отсутствует доступ к репозиторию Docker Hub, то необходимо подготовить образ на том устройстве, где такой доступ имеется, а затем скопировать готовый образ на сервер и развернуть его в контейнере.

Для экспорта созданного образа из среды Docker выполните команду:

docker save -o file_path image_name

Описание параметров команды:

file_path - путь к tar файлу, в который будет экспортирован образ.
image_name - имя образа, который необходимо экспортировать.

Для импорта файла образа в Docker выполните команду:

docker load -i file_path

Описание параметров команды:

file_path - путь к tar файлу, из которого будет импортирован образ.

Установка Redis и Docker на одном хосте¶

Если установка Docker выполняется на тот же хост, где был установлен Redis, то может возникнуть проблема сетевого доступа из Docker-контейнера к Redis. По умолчанию Redis прослушивает сетевой интерфейс обратной связи (127.0.0.1), чтобы доступ осуществлялся локально с компьютера, на котором он установлен. Однако, при запуске Docker-контейнера используется другой сетевой интерфейс (среды Docker), который игнорируется компонентом Redis. Существует несколько возможных вариантов решения данной проблемы.

Использование единой сети хоста¶

Измените команду docker run в скриптах run.bat (для Windows) или run.sh (для Linux), в папке Docker\jinni основой сборки TESSA следующим образом:

добавьте параметр --network host - данная конфигурация позволяет создать автономный контейнер, который напрямую подключается к сети хоста Docker без сетевой изоляции;
удалите строку с параметром порта -p и его значением (-p $PublicPort:5000);

Tip

Убедитесь, что внутри хоста свободен порт, на котором запускается веб-сервис Jinni (по умолчанию 5000). Если порт занят, то измените его, модифицировав Dockerfile или задав переменную окружения JINNI_LISTEN. Подробнее см. Изменение прослушиваемых конечных точек Jinni.
при запуске run-скрипта для параметра Redis IP address укажите IP адрес Redis, по которому он доступен с хоста (по умолчанию этот адрес соответствует 127.0.0.1).

Запустите скрипт run.bat (для Windows) или run.sh (для Linux) с учётом значений, которые были изменены выше.

Настройка параметров Redis¶

Сначала необходимо узнать IP адрес хоста в сети docker. Для этого выполните команду на хосте:

docker network inspect bridge -f '{{range .IPAM.Config}}{{.Gateway}}{{end}}'

На экране появится IP адрес хоста. Например: 172.17.0.1.

Откройте для редактирования конфигурационный файл redis.conf. В некоторых операционных системах Linux конфигурационный файл может существовать с другим названием redis-stack.conf.

Note

В операционной системе Linux файл может располагаться по пути etc/redis.conf или /etc/redis/redis.conf.

Найдите параметр bind:

bind 127.0.0.1 ::1

Добавьте для него первым значением IP адрес, полученный выше (в нашем случае это 172.17.0.1):

bind 172.17.0.1 127.0.0.1 ::1

Tip

Если параметр bind отсутствует в конфигурационном файле, то его необходимо добавить с содержимым, которое указано строкой выше.

В том же файле найдите параметр protected-mode и замените значение yes на no:

protected-mode no

Tip

Если параметр protected-mode отсутствует в конфигурационном файле, то его необходимо добавить с содержимым, которое указано строкой выше.

Закройте файл, предварительно сохранив изменения.

Теперь необходимо узнать IP адрес Docker-контейнера сети docker. Для этого выполните команду на хосте:

docker inspect -f '{{range.NetworkSettings.Networks}}{{.IPAddress}}{{end}}' jinni

где jinni - название Docker-контейнера, для которого необходимо узнать IP адрес.

На экране появится IP адрес Docker-контейнера. Например: 172.17.0.2.

Теперь необходимо добавить правило файервола для разрешения трафика на порт Redis. Например, для Ubuntu правило выглядит следующим образом:

ufw allow from 172.17.0.2 proto tcp to any port 6379

Перезапустите Redis и Docker-контейнер.

Ошибка работы `WkHtmlToPdf` на некоторых ядрах Linux¶

На некоторых ядрах ОС Linux хоста, где установлен Docker, может происходить ошибка работы инструмента WkHtmlToPdf с сообщением:

WkHtmlToPdf: error while loading shared libraries: libQt5Core.so.5: cannot open shared object file: No such file or directory.

Чтобы устранить данную ошибку измените сгенерированный файл Dockerfile перед созданием Docker-образа build-скриптом (см. Конфигурирование Dockerfile):

перед строкой wkhtmltopdf добавьте строку binutils \;

после строки wkhtmltopdf добавьте строки:

RUN strip --remove-section=.note.ABI-tag /usr/lib/x86_64-linux-gnu/libQt5Core.so.5
RUN apt-get remove --autoremove -y binutils

Выполните создание и сборку образа на основе изменённого Dockerfile.

Веб-сервис Jinni для работы с документами¶

Установка Jinni в среде Docker¶

Подготовка к установке¶

Создание и сборка образа¶

Создание и запуск контейнера¶

Запуск и остановка контейнера¶

Проверка работоспособности веб-сервиса¶

Установка Jinni в Windows¶

Подготовка к установке¶

Запуск веб-сервиса из исполняемого файла¶

Запуск веб-сервиса посредством IIS¶

Проверка работоспособности веб-сервиса¶

Конфигурирование веб-сервиса¶

Конфигурирование Dockerfile¶

Конфигурационные параметры app.json¶

Конфигурационные параметры app-ext.json для Windows¶

Конфигурационные параметры app-ext.json для Docker¶

Часто решаемые задачи¶

Использование одного экземпляра Jinni для разных инсталляций системы¶

Использование монтируемого конфигурационного файла¶

Использование переменной окружения¶

Распределение нагрузки с помощью нескольких экземпляров Jinni¶

Изменение прослушиваемых конечных точек Jinni¶

Изменение прослушиваемой конечной точки с помощью аргументов командной строки в Dockerfile¶

Изменение прослушиваемой конечной точки с помощью переменной окружения в Docker¶

Изменение прослушиваемой конечной точки при запуске веб-сервиса в Windows¶

Экспорт и импорт локального Docker-образа¶

Установка Redis и Docker на одном хосте¶

Использование единой сети хоста¶

Настройка параметров Redis¶

Ошибка работы WkHtmlToPdf на некоторых ядрах Linux¶

Конфигурирование `Dockerfile`¶

Конфигурационные параметры `app.json`¶

Конфигурационные параметры `app-ext.json` для Windows¶

Конфигурационные параметры `app-ext.json` для Docker¶

Ошибка работы `WkHtmlToPdf` на некоторых ядрах Linux¶