Особенности установки ARTA Synergy 4.2 wilkinson 
================================================

**Весь процесс обновления сначала нужно провести на тестовом сервере.**

Процесс обновления на версию 4.2 (wilkinson) с 4.0 (hamming)
-----------------------------------------------------------

При обновлении с версии 4.0 требуется выполнить шаги, аналогичные обновлению на 4.1.
Инструкция доступна по ссылке http://rtd.lan.arta.kz/docs/release-notes/ru/minsky/src/upgrade.html


Процесс обновления с версии 4.1 (minsky) на 4.2 (wilkinson)
-----------------------------------------------------------

**Установка Synergy 4.2 (wilkinson)**

Добавить в файл ``/etc/apt/sources.list`` строку для ветки wilkinson:

``deb [allow-insecure=yes] http://deb.arta.kz/tengri          wilkinson         main contrib non-free``

Обновить список пакетов:

``aptitude update``

Установить Synergy:

``aptitude install arta-synergy-synergy``

После установки новой версии проверить актуальность БД и при необходимости выполнить 
их обновление  в Административном приложении Synergy.


**Обновление Elasticsearch и Kibana**

Synergy 4.2 (wilkinson) работает с Elasticsearch и Kibana версии 7.5.0. Установить их можно
также из ветки wilkinson. 

**ВАЖНО!** Рекомендуется сделать бэкапы индексов. Перед обновлением следует ознакомиться с разделом Breaking Changes 
документации Elasticsearch и откорректировать кастомные индексы при их наличии. Также в случае использования кастомных 
индексов нужно подготовить скрипт для переиндексации после обновления, так как ранее созданные индексы (например, через блок-процессы)
потребуется удалить перед обновлением. Инструкция не включает в себя обновление версий кастомных плагинов Kibana. 
Работу таких плагинов после обновления следует проверить и откорректировать самостоятельно.

Ссылки на документацию Elasticsearch:

	https://www.elastic.co/guide/en/elasticsearch/reference/7.5/elasticsearch-intro.html

	https://www.elastic.co/guide/en/elasticsearch/reference/7.x/breaking-changes-7.0.html

Порядок обновления:

1. сохранить список index patterns и выгрузить из Kibana визуализации и дашборды, это потребуется в дальнейшем для восстановления дашбордов:

.. figure:: ../_static/kibana_patterns.png

.. figure:: ../_static/kibana_export.png

2. остановить Kibana командой ``/etc/init.d/kibana stop`` и удалить все старые индексы: 

    .. code-block:: bash
    
        # curl -X DELETE "localhost:9200/_all?pretty"

3. обновить пакеты elasticsearch и kibana:

``aptitude install elasticsearch kibana``

**Во время установки:** необходимо принять рекомендованные изменения конфигурационных файлов: 

.. code-block:: bash 

    Configuration file '/etc/kibana/kibana.yml'
     ==> Modified (by you or by a script) since installation.
     ==> Package distributor has shipped an updated version.
       What would you like to do about it ?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
          D     : show the differences between the versions
          Z     : start a shell to examine the situation
     The default action is to keep your current version.
    *** kibana.yml (Y/I/N/O/D/Z) [default=N] ? y
    Installing new version of config file /etc/kibana/kibana.yml ...
    Installing new version of config file /etc/systemd/system/kibana.service ...
    Setting up elasticsearch (7.5.0) ...

    Configuration file '/etc/elasticsearch/elasticsearch.yml'
     ==> Modified (by you or by a script) since installation.
     ==> Package distributor has shipped an updated version.
       What would you like to do about it ?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
          D     : show the differences between the versions
          Z     : start a shell to examine the situation
     The default action is to keep your current version.
    *** elasticsearch.yml (Y/I/N/O/D/Z) [default=N] ? y
    Installing new version of config file /etc/elasticsearch/elasticsearch.yml ...
    Installing new version of config file /etc/elasticsearch/jvm.options ...
    Installing new version of config file /etc/elasticsearch/log4j2.properties ...

    Configuration file '/etc/default/elasticsearch'
     ==> Modified (by you or by a script) since installation.
     ==> Package distributor has shipped an updated version.
       What would you like to do about it ?  Your options are:
        Y or I  : install the package maintainer's version
        N or O  : keep your currently-installed version
          D     : show the differences between the versions
          Z     : start a shell to examine the situation
     The default action is to keep your current version.
    *** elasticsearch (Y/I/N/O/D/Z) [default=N] ? y

4. в конфигурационном файле ``/etc/elasticsearch/elasticsearch.yml`` закомментировать при их наличии следующие строки:

    .. code-block:: yaml

	#thread_pool:
	#    index:
	#        queue_size: 1000

5. в файле ``/etc/default/elasticsearch`` указать параметры JAVA_HOME и ES_PATH_CONF:

    .. code-block:: yaml

	# Elasticsearch Java path
	JAVA_HOME=/usr/lib/jvm/java-8-oracle

	# Elasticsearch configuration directory
	ES_PATH_CONF=/etc/elasticsearch

6. выполнить в терминале команды:

    .. code-block:: bash

	# chown -R elasticsearch:elasticsearch /usr/share/elasticsearch

	# chown elasticsearch:elasticsearch /etc/default/elasticsearch

7. удалить файлы старой версии Elasticsearch:

    .. code-block:: bash

	# rm -r /var/lib/elasticsearch/nodes/0/_state/


**Восстановление дашбордов**

1. после переиндексирования зайти в Kibana в раздел Index Patterns, нажать кнопку Create Index, ввести нужные значения для вашего индекса:

.. figure:: ../_static/kibana_create.png

.. figure:: ../_static/kibana_create2.png

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

.. figure:: ../_static/kibana_import.png

.. figure:: ../_static/kibana_import2.png

.. figure:: ../_static/kibana_conflicts.png

После обновления
------------------

#. Если используется индексатор Elasticsearch, включить его в нужных конфигурационных файлах в папке ``/opt/synergy/jboss/standalone/configuration/arta/esb/``

#. После повторного старта ``arta-synergy-jboss`` в Административном приложении переиндексировать формы, файлы, работы и документы, для которых индексатором был указан Elasticsearch. 


Авторизованный доступ в Elasticsearch
-------------------------------------

Для настройки авторизованного доступа в Elasticsearch нужно выполнить следующие шаги:

1. добавить в /etc/elasticsearch/elasticsearch.yml строки и перезапустить Elastic:

    .. code-block:: bash

        xpack.security.enabled: true
        xpack.security.transport.ssl.enabled: true

2. задать пароли для системных пользователей:

    .. code-block:: bash

        # cd /usr/share/elasticsearch/bin
        # ./elasticsearch-setup-passwords interactive

    .. code-block:: bash

	Initiating the setup of passwords for reserved users elastic,apm_system,kibana,logstash_system,beats_system,remote_monitoring_user.
	You will be prompted to enter passwords as the process progresses.
	Please confirm that you would like to continue [y/N]y

	Enter password for [elastic]: 
	Reenter password for [elastic]: 
	Enter password for [apm_system]: 
	Reenter password for [apm_system]: 
	Enter password for [kibana]: 
	Reenter password for [kibana]: 
	Enter password for [logstash_system]: 
	Reenter password for [logstash_system]: 
	Enter password for [beats_system]: 
	Reenter password for [beats_system]: 
	Enter password for [remote_monitoring_user]: 
	Reenter password for [remote_monitoring_user]: 
	Changed password for user [apm_system]
	Changed password for user [kibana]
	Changed password for user [logstash_system]
	Changed password for user [beats_system]
	Changed password for user [remote_monitoring_user]
	Changed password for user [elastic]

3. добавить логин и пароля пользователя kibana в ``/etc/kibana/kibana.yml`` и перезапустить Kibana:

    .. code-block:: yml

	elasticsearch.username: "kibana"
	elasticsearch.password: "rootroot"

4. зайти под пользователем elastic в Kibana в раздел Management -> Security -> Users, создать пользователя для Synergy с ролью Superuser:

.. figure:: ../_static/users.png

.. figure:: ../_static/new_user_create.png

.. figure:: ../_static/new_user.png

5. в файл ``/opt/synergy/jboss/standalone/configuration/arta/elasticConfiguration.xml``  прописать пользователя и пароль и перезапустить JBoss:

    .. code-block:: xml

	<user>synergy</user>
	<password>rootroot</password>

**Обратите внимание**, что, если у вас включена авторизация в Elasticsearch, создание кастомных индексов потребует 
указание пользователя с ролью Superuser в запросах на индексацию. В противном случае индексы создаваться не будут.