Руководство администратора

Проверка наличия установленной Java 11 или 17 в Linux и установка при отсутствии.

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

java -version

Пример результата данной команды, показывающий установленную Java версии 11:

При отсутствии, установите выполнив команду:

sudo apt-get install -y openjdk-11-jdk

Создание пользователя и группы для работы приложения

Для безопасности работы программы создайте пользователя tomcat, сделав его участником группы tomcat с домашним каталогом /opt/vedoc2 (рекомендуем использовать данный каталог для установки программы Ведок) и с оболочкой /bin/false

Команды для этого:

sudo groupadd tomcat

и

sudo useradd -s /bin/false -g tomcat -d /opt/vedoc2 tomcat

Проверка наличия установленной СУБД и установка при отсутсвии

Для проверки установленной СУБД PostgreSQL выполните команду:

find /usr -type f -iwholename "*/bin/postgres"

Если её выполнение вернёт пустое значение, значит в вашей системе не установлена СУБД PostgreSQL.

Для установки выполните следующую команду:

sudo apt-get -y install postgresql postgresql-client

В СУБД имеется встроенный пользователь, обладающий правами на все операции с ней. Данный пользователь имеет имя postgres. Для работы программ, в том числе и Ведок, требуется что бы у него был пароль. Следующая команда выполняет установку для этого пользователя пароля. Пароль совпадает с именем. Если вы хотите установить свой пароль измените значение postgres в окончании команды на своё. Обращаем внимание, что пароль должен быть в одинарных кавычках, а вся команда в двойных.

sudo -u postgres psql -c "ALTER USER postgres WITH PASSWORD 'postgres';"

Программе Ведок для своей работы требуется база данных. Приведенная ниже команда создает базу данных с именем vedocdb (рекомендуем вам создавать БД именно с таким именем):

sudo -u postgres psql -c "CREATE DATABASE vedocdb;"

Более подробное описание состава данного файла по ссылке: https://postgrespro.ru/docs/postgresql/12/auth-pg-hba-conf. При внесении изменений в файл pg_hba.conf произведите перезапуск СУБД.

Установка, настройка и запуск Elasticsearch для полнотекстового поиска

Рекомендуем выполнить загрузку пакета с elasticsearch с нашего FTP сервера. Предварительно в команде выполните замену Наш_FTP на адрес сервера, предоставленного вам вместе с дистрибутивом Ведок. Команда для загрузки:

wget ftp://Наш_FTP/elasticsearch-7.17.21-amd64.deb -q --show-progress --progress=bar:force

Выполните установку загруженного пакета elasticsearch:

sudo dpkg -i ./elasticsearch-7.17.21-amd64.deb

Elasticsearch, по умолчанию, будет использовать около половины оперативной памяти на вашем сервере, требуется выполнить изменение конфигурационного файла для ограничения количества используемой Elasticsearch памяти в файле /etc/elasticsearch/jvm.options. Для выполнения данной операции выполните две команды:

sudo echo "-Xms1g" >> /etc/elasticsearch/jvm.options

и

sudo echo "-Xmx1g" >> /etc/elasticsearch/jvm.options

Замените содержимое конфигурационного файла Elasticsearch по пути /etc/elasticsearch/elasticsearch.yml следующим:

Включите автоматический запуск Elasticsearch при запуске операционной системы, выполнив следующие команды:

sudo systemctl daemon-reload

и

sudo systemctl enable elasticsearch.service

Выполните запуск Elasticsearch:

sudo systemctl start elasticsearch.service

Elasticsearch установлен, запущен и готов для работы. Требуется выполнить назначение паролей встроенным пользователям Elasticsearch. Для этого выполните команду ниже, при её выполнении потребуется ответить на первый вопрос Y и нажать клавишу Enter, на второй вопрос просто нажать клавишу Enter.

sudo /usr/share/elasticsearch/bin/elasticsearch-setup-passwords auto > /etc/elasticsearch/passwords

В результате выполнения команды имена и пароли встроенных пользователей Elasticsearch будут сохранены в файле /etc/elasticsearch/passwords Далее, при настройке конфигурационного файла программы Ведок, потребуется пароль пользователя elastic.

Установка приложения

Дистрибутив программы Ведок поставляется в виде архива. Распакуйте архив в каталог /opt/vedoc2 выполнив команду

sudo unzip -n ./vedoc2.zip -d /opt/vedoc2

Сделайте владельцем всех файлов программы пользователя tomcat

sudo chown tomcat:tomcat /opt/vedoc2 -R

Откройте конфигурационный файл программы application.properties находящийся в каталоге /opt/vedoc2/webapps/vedoc/WEB-INF/classes для редактирования любым редактором с правами root.

Проверьте следующие параметры и, при необходимости, внесите изменения:

1. Имя сервера и имя базы данных для программы, а также пароль пользователя СУБД PostgreSQL.

Установите свои значения, если ранее вы не использовали значения по умолчанию. Значение localhost в параметре main.datasource.url означает, что СУБД находится на том же сервере, где и сама программа Ведок. При подключении к другому серверу СУБД измените это значение на имя или IP адрес вашего сервера СУБД. Параметр main.datasource.password содержит пароль для пользователя СУБД PostgreSQL postgres, если при установке СУБД вы задали другой пароль, то заполните данный параметр этим значением.

2. Файлы, прикрепляемые в карточкам документов, хранятся в файловом хранилище. Следующие параметры определяют пути к ним:

• установка каталога файлового хранилища: jmix.localfs.storage-dir = /opt/vedoc2/.jmix/work/filestorage

• установка каталога для временных файлов: jmix.core.temp-dir = /opt/vedoc2/.jmix/temp

3. Изменение имени компьютера и номера порта приложения

Для своей работы приложение использует порт 8080 и локальное имя компьютера. Если требуется использовать программу в локальной сети выполните изменения:

• в конфигурационном файле application.properties значение localhost в параметре server.address = localhost на имя или IP адрес компьютера, где установлена программа. Номер порта 8080 на требуемое вами значение порта в параметре local.server.port = 8080.

• При условии изменения номера порта, в файле opt/vedoc2/conf/server.xml, найдите блок параметров:

И измените port="8080" на значение, выбранное на предыдущем шаге.

4. Изменение адреса сервера и пароля для работы полнотекстового поиска Elasticsearch.

• вместо значения Password внесите созданное на шаге установки паролей пользователей Elasticsearch значение для пользователя elastic из файла /etc/elasticsearch/passwords в параметре:

jmix.search.elasticsearch.password = Password

• Если вы установили Elasticsearch на другом сервере. Вместо значения 127.0.0.1 установите имя или IP адрес компьютера в параметре:

`jmix.search.elasticsearch.url = http://127.0.0.1:9200

5. Установите значение параметра main.liquibase.contexts следующим:

• main.liquibase.contexts = migrated - программа будет установлена с пустой БД

• main.liquibase.contexts = migrated, demo - программа при первом запуске заполнит базу данных демо примером.

Рекомендуем использовать второй вариант для тестирования, а в дальнейшем создать новую базу данных для работы.

Пробный запуск приложения

Установка бита исполнения у запускаемых файлов

В каталоге приложения /opt/vedoc2/bin установите бит исполнения на все файлы с расширением .sh для пользователя tomcat под которым в дальнейшем будет работать программа, для этого выполните команду:

sudo chmod u+x,o-x /opt/vedoc2/bin/*.sh

Выполните команду для запуска приложения:

sudo /opt/vedoc2/bin/startup.sh

В течении минуты приложение запустится. Для доступа к нему перейдите в браузере по ссылке: http://localhost:8080/vedoc

Если вы изменяли адрес сервера в конфигурационном файле на IP или имя сервера и/или меняли номер порта, ссылка примет соотвествующий вид, к примеру:

http://test:8111/vedoc, здесь test это имя компьютера и 8111 - используемый порт.

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

Учетные данные для входа administrator/administrator – логин/пароль соответственно.

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

sudo /opt/vedoc2/tomcat/bin/shutdown.sh

Создание системного юнита для автоматического запуска

Для автоматического запуска программы создайте файл vedoc2.service в каталоге /etc/systemd/system (для систем использующих систему инициализации systemd) выполнив команду:

sudo vi /etc/systemd/system/vedoc2.service

Заполните данный файл следующим содержанием (приведен пример при использовании Java версии 11 из стандартного репозитория и установки приложения в каталог /opt/vedoc2):

После сохранения файла, для внесения изменений в список системных юнитов выполните команду:

sudo systemctl daemon-reload

Команды запуск/остановка/отслеживание статуса работы приложения:

sudo systemctl start/stop/status vedoc2 - соответственно.

Следующая команда установит автоматический запуск серверной части программы Ведок при загрузке операционной системы:

sudo systemctl enable vedoc2

Проверка наличия Java в Windows и установка при отсутствии.

Убедитесь, что на вашем компьютере установлена Java 11 или 17 версии. Для этого откройте раздел «Установка и удаление программ» и проверьте в списке наличие нужной программы требуемой версии. Если программа не найдена, скачайте ее с нашего FTP сервера и установите, для этого запустите командную строку, выполнив команду CMD и в открывшемся окне выполните:

curl -o %USERPROFILE%\Downloads\bellsoft-jdk11.0.11+9-windows-amd64.msi ftp://Наш_FTP/bellsoft-jdk11.0.11+9-windows-amd64.msi

предварительно изменив Наш_FTP на адрес сервера, присланного вам с дистрибутивом.

Файл сохранится в папке "Загрузки". Установите скачанный файл c настройками по умолчанию.

Проверка наличия СУБД и установка при отсутствии.

Аналогично предыдущему пункту проверьте в разделе "Установка и удаление программ" наличие установленной СУБД. Если СУБД отсутствует выполните её установку, для этого запустите командную строку выполнив команду CMD. В открывшемся окне выполните:

curl -o %USERPROFILE%\Downloads\postgresql-12.3-2-windows-x64.exe ftp://Наш_FTP/postgresql-12.3-2-windows-x64.exe

предварительно изменив Наш_FTP на адрес сервера, присланного вам с дистрибутивом.

Файл сохранится в папке "Загрузки". При выполнении установки обратите внимание на следующие моменты:

• при выборе устанавливаемых компонентов уберите отметку пункта "Stack Builder"

• на шаге выбора локали для кластера СУБД сделайте выбор "Russian, Russia"

Итоговая информация перед началом установки будет выглядеть следующим образом:

Вместе с СУБД будет установлен пакет pgAdmin. Далее он понабодится для создания базы данных. Также с его помощью вы можете создавать резервные копии базы данных или проводить восстановление базы данных в случае аварии.

Распаковка приложения

Дистрибутив поставляется в виде архива. Создайте каталог, в котором будет размещаться программа (не используйте в имени пути каталога русских букв). Распакуйте архив в созданный каталог. Рекомендуем вам использовать каталог с именем vedoc2. Ниже содержимое каталога после распаковки архива с программой:

Особенности при использовании СУБД MS SQL Server

Запустите SQL Management Studio и разверните ветку Безопасность под узлом вашего сервера. В "Имена для входа" выберите логин sa и посмотрите его свойства.

Скорее всего, у вас там Russian. При данной настройке установка и работа Ведок будет происходить не корректно. Измените для логина sa язык по умолчанию на English - us_english.

Создание базы данных

• При использовании MS SQL Server

Средствами СУБД создайте пустую базу данных c именем vedocdb (рекоомендуем вам создавать БД именно с таким именем) - данное имя успользуется по умолчанию в конфигурационном файле. Если вы создадите базу данных с другим именем потребуется внести изменения в конфигурационный файл программы. В создаваемой базе данных настройка «Параметры сортировки» должна быть «Cyrillic_GeC_AS»

• При использовании PostgreSQL

Для создания базы данных воспользуйтесь установленной программой pgAdmin. При создании базы данных в PostgreSQL введите только имя базы данных не изменяя другие параметры.

Установка, настройка и запуск Elasticsearch для полнотекстового поиска для Windows

Программа Ведок для поиска по содержимому справочников и прикрепленных к карточкам файлов использует внешнее приложение Elasticsearch. Выполните следующие шаги для скачивания данной программы, её установке, настройке и автоматическому запуску.

Запустите командную строку выполнив команду CMD. В открывшемся окне выполните команду:

curl -o %USERPROFILE%\Downloads\elasticsearch-7.17.21-windows-x86_64.zip ftp://Наш_FTP/elasticsearch-7.17.21-windows-x86_64.zip

предварительно изменив Наш_FTP на адрес сервера, присланного вам с дистрибутивом.

Файл сохранится в папке "Загрузки". Распакуйте полученный архив с программой в каталог с именем elasticsearch-7.17.21. Ниже пример содержимого данного каталога при установке на диск C:

Выполните первый запуск Elasticsearch для проверки его работы и статуса. Для этого запустите файл elasticsearch.bat из каталога C:\elasticsearch-7.17.21\bin

После запуска программы Elasticsearch откройтся окно с логом программы:

В браузере перейдите по ссылке http://localhost:9200

Появление окна с запросом пароля является признаком того, что Elasticsearch запущен. Программа Ведок для поисковых запросов и отправки на индексацию элементов использует доступ по имени и паролю к Elasticsearch. Следующая последовтельность команд устанавливает пароли встроенным пользователям Elasticsearch. Не прерывая работы запущенного Elasticsearch, откройте окно с командной строкой, выполнив команду CMD и в нём выполните команду:

C:\elasticsearch-7.17.21\bin\elasticsearch-setup-passwords.bat auto

Введите символ 'y' в ответ на запрос и нажмите клавишу Enter. На экране появятся созданные пароли для встроенных пользователей программы Elasticsearch. Вот пример:

Сохраните все созданные пароли для всех пользователй программы Elasticsearch. В дальнейшем вам понабодится пароль от учетной записи elastic. Не закрывайте окно с командной строкой, оно понадобится позднее.

Сейчас вы можете проверить информацию о запущенной программе Elasticsearch. Вернитесь в браузер и в окне для авторизации внесите имя пользователя elactic, а в поле пароль, созданный ранее пароль для этого пользователя. Картинка ниже отображает состояние программы Elasticsearch после ввода учетных данных:

Последними шагами при настройке Elasticsearch являются установка его как системной службы и изменение настройки запуска. Завершите работу Elasticsearch, закрыв окно в котором отображаются его логи. Перейдите в окно с командной строкой и выполните следующие две команды:

elasticsearch-service.bat install

и

elasticsearch-service.bat manager

Первая команда выполняет установку системной службы для управления запуском и остановкой Elasticsearch:

Вторая открывает окно настроек:

Установите режим запуска Automatic, нажмите кнопку Применить и далее запустите службу кнопкой Start.

На этом установка и настройка Elasticsearch завершена.

Измение конфигурации программы в соответствии с текущими настройками

Откройте конфигурационный файл программы application.properties находящийся в каталоге C:\vedoc2\webapps\vedoc\WEB-INF\classes для редактирования любым редактором. Если вы производили установку в другой каталог, то данный файл будет располагаться по другому пути.

Проверьте следующие параметры и, при необходимости, внесите изменения:

1. Имя базы данных для программы и пароль пользователя при использовании СУБД PostgreSQL.

Установите свои значения, если ранее вы не использовали значения по умолчанию. Значение localhost в параметре main.datasource.url означает, что СУБД находится на том же сервере, где и сама программа Ведок. При подключении к другому серверу СУБД измените это значение на имя или IP адрес вашего сервера СУБД. Параметр main.datasource.password содержит пароль для пользователя СУБД PostgreSQL postgres, если при установке СУБД вы задали другой пароль, то заполните данный параметр этим значением.

2. Имя базы данных и пароль пользователя при использовании СУБД MS SQL Server.

Значение localhost в параметре main.datasource.url означает, что СУБД находится на том же сервере, где и сама программа Ведок. При подключении к другому серверу СУБД измените это значение на имя или IP адрес вашего сервера СУБД. databaseName=vedocdb - данный параметр задает имя базы данных Ведок. Если при при её создании было использовано другое - внесите изменение. Параметр main.datasource.password должен содержать пароль пользовтеля СУБД sa, от имени которого выполнялось создание базы данных.

3. Файлы, прикрепляемые к карточкам документов хранятся в файловом хранилище. Следующие параметры определяют пути к ним:

• определение пути до каталога файлового хранилища: jmix.localfs.storage-dir = C:\\vedoc2\\.jmix\\work\\filestorage

• определение пути до каталога временных файлов: jmix.core.temp-dir = C:\\vedoc2\\.jmix\\temp

4. Изменение имени компьютера и номера порта приложения:

Для своей работы приложение использует порт 8080 и локальное имя компьютера. Если требуется использовать программу в локальной сети выполните изменения:

• в параметре server.address = localhost на имя или IP адрес компьютера, где установлена программа. Номер порта 8080 на требуемое вами значение порта в параметре local.server.port = 8080.

• если на предыдущем шаге вы изменили номер порта для программы Ведок, то в файле C:\vedoc2\conf\server.xml, найдите блок параметров:

И измените port="8080" на значение, заданное на предыдущем шаге.

5. Изменение адреса сервера и пароля для подключения полнотекстового поиска Elasticsearch.

• Если вы установили Elasticsearch на другом сервере, то установите вместо 127.0.0.1 имя или IP адрес этого сервера в параметре:

jmix.search.elasticsearch.url = http://127.0.0.1:9200

• В параметре: jmix.search.elasticsearch.password = Password вместо Password внесите созданный на шаге установки паролей пользователей Elasticsearch значение для пользователя elastic

6. Установите значение параметра main.liquibase.contexts следующим:

• main.liquibase.contexts = migrated - программа будет установлена с пустой БД

• main.liquibase.contexts = migrated, demo - программа при первом запуске заполнит базу данных демо примером.

Рекомендуем использовать второй вариант для тестирования,а в дальнейшем создать новую базу данным для работы.

7. Установите путь до файла логов программы в параметре logging.file.name = vedoc2.log убрав знак # начале строки и установите знак # в начале строки для имени файла логов для среды Linux.

Пробный запуск приложения

Запустите файл startup.bat из каталога C:\vedoc2\bin

Появление сообщения: INFO: Server strartup in …. ms означает успешный запуск приложения.

Для доступа к приложению перейдите в браузере по ссылке http://localhost:8080/vedoc

Если конфигурационном файле вместо localhost было установлено имя или IP адреса компьютера, например test и/или изменен номер порта, например на 8111, то ссылка для программы примет вид http://test:8111/vedoc

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

Учетные данные для входа administrator/administrator – логин/пароль соответственно.

Для остановки приложения запустите файл shutdown.bat из этого же каталога.

Настройка запуска/остановки программы Ведок через системную службу

Более удобным является управление запуском и остановкой программы Ведок через системную службу. Следующие шаги опишут как это сделать.

• Запустите CMD от имени локального администратора и выполните команды.

cd c:\vedoc2\bin\

а затем

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

В среде операционной системы Linux

1. Настройка сервера приложений Tomcat для работы через HTTPS с использованием Let’s Encrypt (на примере ОС Ubuntu) Установка пакета для работы с Let`s Encrypt и генерация сертификатов:

2. Для сертификатов создайте каталог cert внутри каталога /opt Скопируйте полученные файлы сертификатов в созданный каталог и измените права доступа к ним для возможности чтения пользователем tomcat.

3. После получения ключей измените файл server.xml в каталоге /opt/vedoc2/conf: Закоментировать:

Вставить:

В данном случае файлы сертификатов

располагаются в каталоге /opt/cert, при их расположении в другом каталоге, путь должен быть соответствующий.

В среде операционной системы Windows

Для создания самоподписанного сертификата сервера используется утилита keytool (для Linux также может быть использован этот же метод, для запуска утилиты не требуется писать полный путь). При необходимости работы самоподписанного сертификата на локальном компьютере (localhost) внесите в него альтернативные имена SubjectAlternativeName (SAN). То есть, URL нашего приложения vedoc на локальном компьютере будет иметь следующий адрес: https://localhost:8443/vedoc/

Для создания сертификата с ключом -genkey. Символы переноса '\ использованы только для наглядности представления команды; в реальности они могут быть убраны и команда может быть представлена одной строкой.

Необходимо обратить внимание на опцию -ext (4-ая строка), которая позволяет включить в сертификат альтернативные имена SAN, используя в качестве разделителя символ запятой. Помните, что наименования альтернативных имен должны начинаться с символов, т.е. если вместо localhost использовать значение 127.0.0.1 утилита keytool выбросит исключение :

java.lang.RuntimeException: java.io.IOException: DNSName components must begin with a letter.

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

SAN=dns:localhost,IP:10.10.10.1

Сертификат и закрытый ключ будут созданы в файле keystore.jks

Данный файл является хранилищем по умолчанию для java. Более подробная информация о нём по ссылке

Настройка SSL конфигурации сервера Tomcat.

Tomcat может использовать две различные SSL реализации:

• JSSE (Java Secure Socket Extension) реализацию как часть Java runtime, начиная с версии 1.4;

• APR (Apache Portable Runtime) реализацию, использующую по умолчанию OpenSSL engine.

Выбираем первый вариант и настраиваем Tomcat на использование библиотеки Java для безопасных сетевых соединений JSSE, в котором реализованы протоколы SSL и TLS. В первую очередь переносим в директорию /conf созданное на предыдущем шаге хранилище сертификата keystore.jks.

Файл конфигурации server.xml

Переходим в директории /conf открываем файл конфигурации server.xml на редактирование и вносим следующие изменения, в которох указывается порт 8443, схема HTTPS, протокол TLS, тип хранилища JKS и его месторасположение conf/keystore.jks. В обязательном порядке следует указать пароль доступа к хранилищу и алиас ключа/сертификата.

Закоментировать:

Вставить новую секцию с параметрами:

Поскольку APR реализацию не используем, то комментируем строку определения слушателя AprLifecycleListener.

Общая настройка

1. Для перевода WEB-приложение в режим защищенного соединения необходимо настроить дескриптор приложения сервера Tomcat в файле conf/web.xml. Добавитье следующий код в конец этого файла до заверщающего тэга

   :