Установка PC версии 5

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

  • с помощью скрипта инсталляции
  • запуск в среде контейнеризации Docker
  • вручную.

Перед установкой

Подготовка БД

Поддерживаемые СУБД — Postgres, Oracle, MS SQL.

Перед установкой необходимо создать БД PCS и БД PCSS (опционально, только при использовании компонента Server Signer).

Создать пользователя, под которым PC будет подключаться к БД. Необходимые привилегии CRUD + Alter.

Структуру БД создавать не нужно. При первом подключении PC сам создаст все необходимые таблицы.

Java

Для вариантов установки "С помощью скрипта инсталляции" и "Вручную" необходимо yстановить последнюю версию JRE 11.

С помощью скрипта инсталляции

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

Справка скрипта инсталляции

Execution modes:
  -i  Install. Set it for process installation. 
  -h  Help. Will show this help.

Installation options:
  -r  Register system (only on PCS, matters with -i option). Optional. For registration you must put you register system request file to "customer" directory before. Contact you supplier for obtain this request file.

 PC roles (must selected at least one of them):
  -S  PC Server
  -P  PC Pusher
  -E  External / PCIS External
  -G  PC Server Signer (only for version 5.2 and above)

Install wildfly database driver (mandatory for PCS and PCSS modules):
  -p  PostgreSQL
  -o  Oracle
    Need to set up parameter - jdbc version:
    8  JDBCv8. Certified with JDK8 and JDK11. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2
    0  JDBCv10. Implements JDBC 4.3 spec and certified with JDK11. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2
    1  JDBCv11. Implements JDBC 4.3 spec and certified with JDK11 and JDK17. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2
  -m  MS SQL

Examples
  ./install.sh -i -SPEG -r -o8
  also like
  ./install.sh -iSPEGro8
    will install PCS, PCP, PCE, PCSS, Oracle JDBC8 Driver and execute register system request

  ./install.sh -i -Sp
  also like
  ./install.sh -Sp
    will install PCS with Postgres drivers

Конфигурирование инсталлятора

Перед установкой необходимо сконфигурировать инсталлятор для автоматической настройки компонентов PC. Конфигурирование производится путём редактирования раздела CUSTOMER Config файла install.conf. В конфигурационном файле подлежат настройке следующие параметры:

  • Данные для подключения к БД PCS.
  • Данные для подключения к БД PCSS.
  • Адрес сервера PCS. Этот адрес будет использоваться компонентом PC External для подключения к PC Server.

СУБД Oracle

Особенности установки под СУБД Oracle приведены ниже.

SID/Service Name

При использовании СУБД Oracle необходимо указать, каким образом происходит выбор необходимой БД - с помощью SID или Service Name.

Версия драйвера

Версия OJDBC Поддерживаемые драйвером версии Java и СУБД
8 Certified with JDK8 and JDK11. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2
10 Implements JDBC 4.3 spec and certified with JDK11. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2
11 Implements JDBC 4.3 spec and certified with JDK11 and JDK17. Supports Oracle Database versions - 21c, 19c, 18c, and 12.2

Источник — https://www.oracle.com/database/technologies/faq-jdbc.html#01_02.

Пример конфигурации

###################################################
#
# CUSTOMER Config
#
###################################################

PC_PATH='/opt/pc'
PC_PRODUCT='PayControl'

#   PC Servers Settings
##  PCS
### DB
PCSDB_HOST='hostname:port'
PCSDB='DB'
PCSDB_USER='user'
PCSDB_PASSWD='password'

# Oracle connection string delimiters:
# - use ':', if PCSDB contains SID
# - use '/', if PCSDB contains Service Name
PCSDB_Oracle_delimiter=':'


##  PCServerSigner
### DB
PCSSDB_HOST='hostname:port'
PCSSDB='DB'
PCSSDB_USER='user'
PCSSDB_PASSWD='password'

# Oracle connection string delimiters:
# - use ':', if PCSSDB contains SID
# - use '/', if PCSSDB contains Service Name
PCSSDB_Oracle_delimiter=':'


##  PC External / PCIS External
PCS_HOSTNAME_PORT='localhost:8080'

Установка

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

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

  2. Распаковать:

    tar -xzvf paycontrol_distrib.tar.gz

  3. Перейти в директорию с распакованными файлами.

  4. При необходимости выполнения регистрации прикладной системы во время инсталляции, необходимо на сервере, на который будет производиться установка компонента PCS скопировать файл, содержащий запрос на регистрацию прикладной системы в директорию customer/ дистрибутива. Название файла с запросом на регистрацию прикладной системы имеет следующий вид RegisterSystemRequest 5.1 [company_name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx].json

  5. Запустить установочный скрипт с привилегиями root, с требуемыми параметрами.

Результат выполнения инсталляционного скрипта

Результат выполнения инсталляционного скрипта является:

  • установлен сервер приложений WildFlу (директория /opt);
  • добавлена служба wildflу и включён её автозапуск;
  • добавлены драйвера СУБД (опционально);
  • добавлены источники данных (только для PC Server и PC Server Signer, при необходимости);
  • развёрнуты модули сервера PC в WildFly;
  • прикладная система зарегистрирована в PC (при установленном параметре r и предоставленном запросе регистрации прикладной системы).

Результат регистрации - вывод на экран идентификатора системы в конце журнала работы инсталляционного скрипта (systemid).

Пример:

    {
        "answer_type": "system_info",
        "answer": {
        "result": {
            "error_message": "Success",
            "error_code": 0
        },
        "system_info": {
            "billing_period": 365,
            "system_id": "e64a67c9-73e9-462c-9c27-2d0195a2bd23",
            "description": "Bank1 Payments",
            "report_template_path": "/opt/pc/report.docx",
            "created_at": "2020-03-23 12:34:1.895",
            "pc_is_external_url": "https://bank1.example.com/pc-client-api/",
            "register_request": "eyJyZXF1ZXN0I...Xc9PSJFSSZEhTQUFKRXc9PSJEhTQUFKRXc9PSZXN0Ijp7InFyVJ9",
            "pc_is_internal_url": "http://localhost:8080/pc-pusher-api/",
            "is_deleted": false,
            "license_info": {
                "users_count": 20,
                "used": 0,
                "message": "LICENSE NOT FOUND! You are using unlicensed demo-only version of the service"
            },
            "billing_type": 3,
            "user_keys_expiration_period": 365,
            "name": "Bank1"
        }
    },
    "answer_version": 3
}

В приведённом примере идентификатором зарегистрированной прикладной системы является e64a67c9-73e9-462c-9c27-2d0195a2bd23. В дальнейшем этот идентификатор понадобится при настройке прикладной системы на работу с сервером PC. Если значение идентификатора прикладной системы утеряно, свяжитесь с компанией SafeTech для его уточнения.

Примеры параметров запуска

Примеры ниже приведены для установки компонентов PC сервера с драйвером PostgreSQL (параметр p).

Всё на одном сервере

  • Без регистрации прикладной системы

    sudo ./install.sh -ipSPEG

  • С регистрацией прикладной системы

    sudo ./install.sh -ipSPEGr

PC Server

  • Без регистрации прикладной системы

    sudo ./install.sh -ipS

  • С регистрацией прикладной системы

    sudo ./install.sh -ipSr

PC External

sudo ./install.sh -iE

PC Server Signer

sudo ./install.sh -ipG

Контроль

Вывод журнала в консоль в реальном времени

tail -n 300 -f /opt/wildfly/standalone/log/server.log

Просмотр успешности развёртывания компонентов сервера

ls -la /opt/pc/deployments/

Если компонент сервера развёрнут успешно, рядом с файлом компонента сервера создаётся файл с аналогичным именем файлу сервера с расширением .deployed.

Под Docker

Образы

Поддерживают PC с версии 3.5.

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

  • registry.paycontrol.org/pc/pc_wildfly:v5-pgsql
  • registry.paycontrol.org/pc/pc_wildfly:v5-oracle8
  • registry.paycontrol.org/pc/pc_wildfly:v5-oracle10
  • registry.paycontrol.org/pc/pc_wildfly:v5-oracle11
  • registry.paycontrol.org/pc/pc_wildfly:v5-mssql

В образах с драйвером для СУБД Oracle, цифрой обозначена версия OJDBC драйвера. Таблица соответствия доступна по ссылке.

Подготовка

Размещение файлов модулей сервера

В соответствии с выбранной схемой включения модулей сервера в инфраструктуру, разместить файлы модулей (.ear/.war) в директории deployments соответствующих контейнеров. Модуль PCSS следует разместить в одном контейнере с PCS, однако, размещение в отдельном также допускается (при обеспечении их сетевой связности и требует для этого дополнительных настроек, не описанных в этом документе в настоящее время).

Окружение

Подключаемые тома:

  • deployments — в эту директорию размещаются ear/war-файлы модулей компонентов сервера PC. У пользователя, от имени которого запускается процесс в контейнере (1000:1000) должны быть права на чтение/запись в директорию. Файлы модулей доступны в репозитории по адресу https://repo.paycontrol.org/server/maven/tech/paycon/server/;
  • themes — нужна только для PCE, в случае необходимости размещать темы оформления для мобильного приложения PC;
  • log — используется для записи основным процессом контейнера файлов журнала работы WildFly;
  • pki — только для PCS, опционально, при использовании PKI на базе OpenSSL.

Дополнительные параметры запуска модуля PCE (передаются посредством переменной окружения JAVA_OPTS):

  • pc_url — адрес сервера PCS. Значение по умолчанию — http://localhost:8080/pc-api/;
  • pc_logRequests — включение журналирования запросов. Значение по умолчанию — false;
  • pc_locale — смена языка сообщений об ошибках, возвращаемых сервером мобильному приложению. Доступный вариант — ru. Значение по умолчанию en;
  • pc_themesPath — Используется для указания пути к директории, с помощью которой осуществляется публикация файлов тем для приложения PC. Значение по умолчанию — /opt/wildfly/pc_themes/;

Пример

Ниже приведены примеры файлов для схемы включения PCS, PCSS, PCP — в одном контейнере, PCE — в другом.

.env

Параметры подключения к БД PCSS опциональны, и необходимы только при использовании модуля Server Signer.

PCS_DB_CONNECTION_URL=jdbc:postgresql://dbserver.example.com:5432/pcs
PCS_DB_USER=user
PCS_DB_PASSWORD=password
PCSS_DB_CONNECTION_URL=jdbc:postgresql://dbserver.example.com:5432/pcss
PCSS_DB_USER=user
PCSS_DB_PASSWORD=password

docker-compose.yml

  • Подключение директории /opt/pc/pki/ необходимо при использовании PKI на базе OpenSSL.
  • Подключение директории /opt/jboss/wildfly/pc_themes/ опционально, и необходимо в случае размещения файлов тем оформления для мобильного приложений PC;
version: '3.3'
services:
    pc:
        ports: 
            - 8080:8080
        restart: unless-stopped
        container_name: "pc_srv_int"
        volumes:
            - "/opt/pc/srv_int/deployments/:/opt/jboss/wildfly/standalone/deployments/:z"
            - "/opt/pc/srv_int/log/:/opt/jboss/wildfly/standalone/log/:z"
            - "/opt/pc/srv_int/pki/:/opt/pc/pki/:z"
        environment:
            - 'JAVA_OPTS=-Dfile.encoding=UTF-8'
            - PCS_DB_USER
            - PCS_DB_PASSWORD
            - PCS_DB_CONNECTION_URL
            - PCSS_DB_USER
            - PCSS_DB_PASSWORD
            - PCSS_DB_CONNECTION_URL
        image: "registry.paycontrol.org/pc/pc_wildfly:v5-pgsql"
    pce:
        ports: 
            - 8081:8080
        restart: unless-stopped
        container_name: "pc_external"
        volumes:
            - "/opt/pc/external/deployments/:/opt/jboss/wildfly/standalone/deployments/:z"
            - "/opt/pc/external/themes/:/opt/jboss/wildfly/pc_themes/:z"
            - "/opt/pc/external/log/:/opt/jboss/wildfly/standalone/log/:z"
        environment:
            - 'JAVA_OPTS=-Dpc_url=http://pc:8080/pc-api/ -Dpc_locale=ru -Dpc_themesPath=/opt/jboss/wildfly/pc_themes/ -Dfile.encoding=UTF-8'
        image: "registry.paycontrol.org/pc/pc_wildfly:v5-pgsql"

Включение и конфигурирование HTTPS

В некоторых организациях предъявляются требования к трафику, передаваемому в сети компании, между серверными компонентами. Обязательным требованием для промышленного окружения является обеспечение TLS защиты при подключении мобильного SDK к серверу PC.

Данное описание актуально только для запуска под Docker. Описание способа включения HTTPS для запуска в среде ОС представлено в справочном руководстве, в разделе Включение и конфигурирование HTTPS.

Добавление сертификата, для включения TLS

По умолчанию, TLS уже включён на порту 8443, но при этом "по умолчанию" используется самоподписанный сертификат.

Для добавления/обновления релевантного сертификата необходимо выполнить следующие действия:

  1. Составить цепочку сертификатов. Из файлов сертификатов в формате PEM (Base64) составить цепочку путём соединения в новом файле с расширением crt, например fullchain.crt. Для этого в новый файл с помощью текстового редактора нужно добавить сертификат корневого УЦ, промежуточных, и собственно сертификат сервера.

  2. Создать контейнер формата pkcs12:

    openssl pkcs12 -export -in fullchain.crt -inkey private_key.key -out keycontainer.p12

    при экспорте следует задать пароль password для приватного ключа.

  3. Создать JKS-контейнер из PKCS12:

    keytool -importkeystore -srckeystore keycontainer.p12 \
    -srcstoretype PKCS12 \
    -destkeystore application.keystore \
    -deststoretype JKS

    при импорте указать password, при экспорте указать пароль к контейнеру.

  4. Скопировать application.keystore например в директорию запуска compose-контейнера.

  5. Добавить в docker-compose.yml подключение файла, например:

    version: '3.7'
services:
  pcs:
    volumes:
      - "./application.keystore:/opt/jboss/wildfly/standalone/configuration/application.keystore:z"

  6. Перезапустить контейнер.

  7. Проверить подключение:

    docker-compose exec <container-name> openssl s_client -connect <server-name>:8443

    Verify Result должен быть 0.

  8. Разрешить доступ к порту 8443 контейнера, например:

    version: '3.7'
services:
  pcs:
    ports:
      - "${PC_SECURE_PORT}:8443"

Добавление сертификатов корпоративных УЦ

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

FROM registry.paycontrol.org/pc/pc_wildfly:v5-pgsql
COPY rootCA.pem .
USER root
RUN keytool -import -alias "Company Name" -noprompt -keystore /etc/ssl/certs/java/cacerts -storepass changeit -file rootCA.pem && rm rootCA.pem
USER jboss

где

  • alias — алиас сертификата, который будет указан в хранилище для облегчения идентификации сертификата.
  • root_corp.cer — корневой файл корпоративного УЦ.
  • changeit — пароль по умолчанию для хранилища сертификатов.

Как минимум в CN сертификата должен быть адрес, по которому происходит обращение к серверу (DNS или IP). Если этого будет недостаточно, тогда добавить в SAN сертификата.

Переключение схемы и порта

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

Вручную

Установка Wildfly

Linux

  • Распаковать Wildfly, например, в /opt/.
  • Создать символьную ссылку /opt/wildfly на распакованную директорию:
ln -s /opt/wildfly-26.1.3.Final/ /opt/wildfly

Далее по тексту, под WF_PATH имеется в виду адрес созданной символьной ссылки.

Windows

  • Распаковать Wildfly, например, в C:\.
  • Создать символьную ссылку, к примеру C:\wildfly, на распакованную директорию. Пример команды:
mklink /D C:\wildfly C:\wildfly-26.1.3.Final\

Удаление настроек WildFly по-умолчанию

При конфигурировании Wildfly можно (при переводе системы в промышленную эксплуатацию - рекомендуется) удалить пример источника данных и страницу-приветствие. Для этого в файле standalone.xml необходимо убрать (либо закомментировать) следующие объекты:

<datasource jndi-name="java:jboss/datasources/ExampleDS" pool-name="ExampleDS" enabled="true" use-java-context="true">
    connection-url>jdbc:h2:mem:test;DB_CLOSE_DELAY=-1;DB_CLOSE_ON_EXIT=FALSE</connection-url>
    <driver>h2</driver>
    <security>
        <user-name>sa</user-name>
        <password>sa</password>
    </security>
</datasource>

<default-bindings context-service="java:jboss/ee/concurrency/context/default" datasource="java:jboss/datasources/ExampleDS" managed-executor-service="java:jboss/ee/concurrency/executor/default" managed-scheduled-executor-service="java:jboss/ee/concurrency/scheduler/default" managed-thread-factory="java:jboss/ee/concurrency/factory/default"/>

<driver name="h2" module="com.h2database.h2">
    <xa-datasource-class>org.h2.jdbcx.JdbcDataSource</xa-datasource-class>
</driver>

<handlers>
    <file name="welcome-content" path="${jboss.home.dir}/welcome-content"/>
</handlers>

<location name="/" handler="welcome-content"/>

Настройка подключения к БД

Добавление JDBC-драйвера СУБД

PostgreSQL

  • Скачать актуальный JDBC-драйвер по адресу https://jdbc.postgresql.org/
  • Создать директорию WF_PATH/modules/org/postgresql/main/
  • В директорию WF_PATH/modules/org/postgresql/main/ поместить скачанный postgresql-42.*.*.jar
  • Создать в этой же папке файл module.xml следующего содержания, указав имя файла драйвера вместо JAR_PATH:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="org.postgresql">
  <resources>
     <resource-root path="JAR_PATH"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.servlet.api" optional="true"/>
  </dependencies>
</module>
  • Добавить установленный модуль в качестве драйвера для подключения к СУБД в файл WF_PATH/standalone/configuration/standalone.xml, в секцию <datasources/drivers>, добавив следующий блок:
<driver name="postgresql" module="org.postgresql">
    <driver-class>org.postgresql.Driver</driver-class>
</driver>

MS SQL

  • Скачать JDBC-драйвер с сайта Microsoft - https://docs.microsoft.com/ru-ru/sql/connect/jdbc/download-microsoft-jdbc-driver-for-sql-server?view=sql-server-ver15
  • Создать директорию WF_PATH/modules/system/layers/base/com/microsoft/sqlserver/main/
  • В директорию распаковать файлы и директории драйвера. Файлы драйвера (*.jar) должны располагаться непосредственно в директории main/
  • Создать в этой же директории файл module.xml следующего содержания, заменив JAR_PATH на имя загруженного файла драйвера, например на mssql-jdbc-x.x.x.jre11.jar:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.3" name="com.microsoft.sqlserver">
  <resources>
    <resource-root path="JAR_PATH"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
    <module name="javax.xml.bind.api"/>
  </dependencies>
</module>

  • Добавить установленный модуль в качестве драйвера для подключения к СУБД в файл WF_PATH/standalone/configuration/standalone.xml, в секцию <datasources/drivers>, добавив следующий блок:

    <driver name="mssql" module="com.microsoft.sqlserver">
  <driver-class>com.microsoft.sqlserver.jdbc.SQLServerDriver</driver-class>
</driver>

Oracle

  • Скачать актуальный JDBC-драйвер по адресу https://www.oracle.com/database/technologies/appdev/jdbc-downloads.html
  • Создать директорию WF_PATH/modules/org/postgresql/main/
  • В директорию WF_PATH/modules/system/layers/base/com/oracle/main/ поместить скачанный ojdbc*.jar.
  • Создать в этой же папке файл module.xml следующего содержания, указав имя файла драйвера вместо JAR_PATH:
<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:jboss:module:1.0" name="com.oracle">
  <resources>
     <resource-root path="JAR_PATH"/>
  </resources>
  <dependencies>
    <module name="javax.api"/>
    <module name="javax.transaction.api"/>
  </dependencies>
</module>
  • Добавить установленный модуль в качестве драйвера для подключения к СУБД в файл WF_PATH/standalone/configuration/standalone.xml, в секцию <datasources/drivers>, добавив следующий блок:
<driver name="com.oracle" module="com.oracle">
    <driver-class>oracle.jdbc.driver.OracleDriver</driver-class>
</driver>

Добавление источников данных

PostgreSQL

PCS

В файл WF_PATH/standalone/configuration/standalone.xml добавить новый источник данных в секцию <datasources></datasources> заменив pcs-db-host, port, pcs-db, pcs-user, pcs-pass:

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerDS" pool-name="PCServerDS" enabled="true" use-ccm="true">
    <connection-url>jdbc:postgresql://pcs-db-host:port/pcs-db</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <driver>postgresql</driver>
    <security>
        <user-name>pcs-user</user-name>
        <password>pcs-pass</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <background-validation>true</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
</datasource>
PCSS

При использовании компонента PayControl Server Signer в файл WF_PATH/standalone/configuration/standalone.xml нужно добавить источник данных в секцию <datasources></datasources> заменив pcss-db-host, port, pcss-db, pcss-user, pcss-pass:

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerSignerDS" pool-name="PCServerSignerDS" enabled="true" use-ccm="true">
    <connection-url>jdbc:postgresql://pcss-db-host:port/pcss-db</connection-url>
    <driver-class>org.postgresql.Driver</driver-class>
    <driver>postgresql</driver>
    <security>
        <user-name>pcss-user</user-name>
        <password>pcss-pass</password>
    </security>
    <validation>
        <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLValidConnectionChecker"/>
        <background-validation>true</background-validation>
        <exception-sorter class-name="org.jboss.jca.adapters.jdbc.extensions.postgres.PostgreSQLExceptionSorter"/>
    </validation>
</datasource>

MS SQL

PCS

В файл WF_PATH/standalone/configuration/standalone.xml добавить новый источник данных в секцию <datasources></datasources> заменив pcs-db-host, port, pcs-db, pcs-user, pcs-pass:

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerDS" pool-name="PCServerDS" enabled="true" use-ccm="true">
  <connection-url>jdbc:sqlserver://pcs-db-host:port;databaseName=pcs-db</connection-url>
  <driver>mssql</driver>
  <security>
    <user-name>pcs-user</user-name>
    <password>pcs-pass</password>
  </security>
  <pool>
    <min-pool-size>5</min-pool-size>
    <max-pool-size>50</max-pool-size>
    <prefill>false</prefill>
    <use-strict-min>false</use-strict-min>
    <flush-strategy>FailingConnectionOnly</flush-strategy>
  </pool>
  <validation>
    <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
  </validation>
</datasource>
PCSS

При использовании компонента PayControl Server Signer в файл WF_PATH/standalone/configuration/standalone.xml нужно добавить источник данных в секцию <datasources></datasources> заменив pcss-db-host, port, pcss-db, pcss-user, pcss-pass:

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerSignerDS" pool-name="PCServerSignerDS" enabled="true" use-ccm="true">
  <connection-url>jdbc:sqlserver://pcs-db-host:port;databaseName=pcs-db</connection-url>
  <driver>mssql</driver>
  <security>
    <user-name>pcs-user</user-name>
    <password>pcs-pass</password>
  </security>
  <pool>
    <min-pool-size>5</min-pool-size>
    <max-pool-size>50</max-pool-size>
    <prefill>false</prefill>
    <use-strict-min>false</use-strict-min>
    <flush-strategy>FailingConnectionOnly</flush-strategy>
  </pool>
  <validation>
    <valid-connection-checker class-name="org.jboss.jca.adapters.jdbc.extensions.mssql.MSSQLValidConnectionChecker"></valid-connection-checker>
  </validation>
</datasource>

Oracle

PCS

В файл WF_PATH/standalone/configuration/standalone.xml добавить новый источник данных в секцию <datasources></datasources> заменив pcs-db-host, port, pcs-db, pcs-user, pcs-pass, sid(или service name):

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerDS" pool-name="PCServerDS" enabled="true" use-ccm="true">
  <connection-url>jdbc:oracle:thin:@pcs-db-host:port:sid</connection-url>
  <driver>oracle</driver>
  <security>
    <user-name>pcs-user</user-name>
    <password>pcs-pass</password>
  </security>
  <pool>
    <min-pool-size>1</min-pool-size>
    <max-pool-size>5</max-pool-size>
    <prefill>true</prefill>
  </pool>
  <validation>
    <check-valid-connection-sql>select 1 from dual</check-valid-connection-sql>
    <validate-on-match>false</validate-on-match>
    <background-validation>true</background-validation>
    <background-validation-millis>10000</background-validation-millis>
  </validation>
</datasource>
PCSS

При использовании компонента PayControl Server Signer в файл WF_PATH/standalone/configuration/standalone.xml нужно добавить источник данных в секцию <datasources></datasources> заменив pcs-db-host, port, pcs-db, pcs-user, pcs-pass, sid(или service name):

<datasource jta="true" jndi-name="java:jboss/datasources/PCServerSignerDS" pool-name="PCServerSignerDS" enabled="true" use-ccm="true">
  <connection-url>jdbc:oracle:thin:@pcss-db-host:port:sid</connection-url>
  <driver>oracle</driver>
  <security>
    <user-name>pcss-user</user-name>
    <password>pcss-pass</password>
  </security>
  <pool>
    <min-pool-size>1</min-pool-size>
    <max-pool-size>5</max-pool-size>
    <prefill>true</prefill>
  </pool>
  <validation>
    <check-valid-connection-sql>select 1 from dual</check-valid-connection-sql>
    <validate-on-match>false</validate-on-match>
    <background-validation>true</background-validation>
    <background-validation-millis>10000</background-validation-millis>
  </validation>
</datasource>

Настройка подключения PC External к PC Server

На сервере PC External необходимо установить адрес сервера PC Server (host и port заменить на реальные значения). Для этого:

  • на Linux в файл WF_PATH/bin/standalone.conf нужно добавить
JAVA_OPTS="$JAVA_OPTS -Dpc_url=http://<host>:<port>/pc-api/"
  • на Windows в файл WF_PATH\bin\standalone.conf.bat выше метки :JAVA_OPTS_SET нужно добавить
set "JAVA_OPTS=%JAVA_OPTS% -Dpc_url=http://<host>:<port>/pc-api/"

Настройка выделения памяти серверу

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

  • на Linux в WF_PATH/bin/standalone.conf указать объём «ОбщийОбъёмОЗУ - 512MB»
  • на Windows в WF_PATH\bin\standalone.conf.bat указать объём «ОбщийОбъёмОЗУ - 1536MB»

Для этого в строке

JAVA_OPTS="-Xms64m -Xmx512m -XX:MetaspaceSize=96M -XX:MaxMetaspaceSize=256m -Djava.net.preferIPv4Stack=true"

поменять значение параметра Xmx на выделяемый объём.

Изменение языка в сообщениях об ошибках с сервера

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

  • на Linux в файл WF_PATH/bin/standalone.conf в строку, в пределах двойных кавычек

    JAVA_OPTS="$JAVA_OPTS -Dpc_url=http://<host>:<port>/pc-api/"

  • на Windows в файл WF_PATH\bin\standalone.conf.bat в строку, в пределах двойных кавычек

    set "JAVA_OPTS=%JAVA_OPTS% -Dpc_url=http://<host>:<port>/pc-api/"

Настройка модуля PCSS

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

  • на Linux в файл WF_PATH/bin/standalone.conf в строку, в пределах двойных кавычек, например:

    JAVA_OPTS="$JAVA_OPTS -Dpc_serversigner_properties=/opt/pc/server_signer.conf"

  • на Windows в файл WF_PATH\bin\standalone.conf.bat в строку, в пределах двойных кавычек, например:

    set "JAVA_OPTS=%JAVA_OPTS% -Dpc_serversigner_properties=D:\\pc\\server_signer.conf"

Пример конфигурационного файла:

## keys encryption secret. Default value is present.
pc.serversigner.secret=SeCr3t4p71v@73keys3ncr9pti0n

## PC Server API url. Default value is `http://localhost:8080/pc-api`
pc.url=http://<pcs-host>:8080/pc-api

## This service URL to be called from PC Pusher. Default value is `http://localhost:8080/pc-server-signer-api/confirm_async`
serversign.url=http://<pcss-host>:8080/pc-server-signer-api/confirm_async

## Logging (optional). Default value is `false`.
# serversign.extendedLog=true

spring.datasource.jndi-name=java:jboss/datasources/PCServerSignerDS

spring.jpa.properties.hibernate.dialect=org.hibernate.dialect.PostgreSQLDialect
spring.jpa.properties.hibernate.ddl-auto=update

Настройка сервера PCS для взаимодействия с PCSS

В БД PCS, таблицу pc_sys_property добавить запись со значениями setting_name=SERVER_SIGNER_PERS_URL и setting_value=<адрес эндпоинта SS>. Например:

insert into pc_sys_property values (nextval('pc_setting_seq'), 'SERVER_SIGNER_PERS_URL', 'http://<pcss-host>:8080/pc-server-signer-api/personalize_async');

Подробнее о параметрах севрера PCS и способах их установки — по ссылке.

Запуск

Для запуска необходимо:

  • Загрузить файлы модулей требуемых компонентов последних версий из репозитория по адресу https://repo.paycontrol.org/server/maven/tech/paycon/server/.

  • Скопировать файл приложения сервера в директорию WF_PATH\standalone\deployments\:

    • на PC Server - файл pc-server-<VERSION>.ear
    • на PC Pusher - файл pc-pusher-<VERSION>.war
    • на PC External - файл pc-external-<VERSION>.war

Один сервер WildFly может запускать одно или несколько приложений сервера

  • Запустить

    • Linux 
    WF_PATH/bin/standalone.sh -b 0.0.0.0`
    • Windows 
    WF_PATH\bin\standalone.bat -b 0.0.0.0`

    где -b 0.0.0.0 - позволяет подключаться к серверу используя любой его интерфейс (опция bind)

  • Дождаться старта WF, проверить, что нет ошибок запуска.

Настройка автозапуска службы сервера

Linux

Для настройки автозапуска службы, перейти в каталог WF_PATH/docs/contrib/scripts/systemd/ и выполнить шаги, описанные в файле README в этом каталоге, за исключением пунктов распаковки и создания символьной ссылки на каталог. Пункт chown -R wildfly:wildfly /opt/wildfly необходимо выполнить с параметрами -RH (параметр «H» указывает, что если на вход подана символьная ссылка, то нужно пойти вглубь каталога, на который она ссылается). Таким образом команда должна выглядеть следующим образом:

chown -RHv wildfly:wildfly /opt/wildfly

При запуске в качестве службы, возможно отклонение запросов. В таком случае необходимо установить параметры JAVA_OPTS в файле standalone.conf:

JAVA_OPTS="$JAVA_OPTS -Djboss.bind.address=0.0.0.0"

Windows

Скопировать папку WF_PATH\docs\contrib\scripts\service\ в папку WF_PATH\bin\

Выполнить

WF_PATH\bin\service\service.bat install /startup

При запуске в качестве службы, возможно отклонение запросов. В таком случае необходимо установить параметры JAVA_OPTS в файле standalone.conf.bat выше метки :JAVA_OPTS_SET.

set "JAVA_OPTS=%JAVA_OPTS% -Djboss.bind.address=0.0.0.0"

URL-фильтрация при совмещении PC Pusher и PC External

При совмещении ролей PC Pusher и PC External на одном сервере необходимо исключить возможность выполнения запросов PC Pusher со стороны сети интернет.

Для этого необходимо со стороны сети интернет разрешить подключения только на конечную точку PC External.

Конечная точка PC External - <host>:<port>/pc-client-api/* Доступ к другим конечным точкам должен быть запрещен.

При этом доступ к PC Pusher со стороны PC Server должен сохраниться. Конечная точка PC Pusher - <host>:<port>/pc-pusher-api/*

Регистрация системы

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

Это действие выполняется путем отправки на PC Server HTTP POST запроса, сформированного ST/Airome. Содержание запроса предоставляется дополнительно.

Для отправки запроса можно использовать любое средство отправки HTTP-запросов.

Примеры

PowerShell
$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Content-Type", "application/json")

$body = "{n  "request`":"eyJyZXF1ZXN0Ijp7InFyVVJMU2NoZW1lIjEE9NoZ+W1lIjEE9NoZW... ...9NoZW1lIjEE+9NoZW1lIjEE9NoZW1lIjEE9PSJ9"`n}"

$response = Invoke-RestMethod 'https://dev.paycontrol.org/v5.0/pc-api/' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json
cURL
curl --location --request POST 'http://<host>:<port>/pc-api/' --header 'Content-Type: application/json' --data '{"request":"eyJyZXF1ZXN0Ijp7InFyVVJMU2NoZW1lIjEE9NoZ+W1lIjEE9NoZW1lIjEE9... ...IjEE9NoZW1lIjEE9PSJ9"}'

После установки

Проверка доступности сервисов

При запросе на серверы по указанным ниже эндпоинтам будут выведены название модуля сервера PC, его версия и версия API.

  • PC Server — http://<IP или имя сервера PC Server>:8080/pc-api/health_check
  • PC Pusher — http://<IP или имя сервера PC Pusher>:8080/pc-pusher-api/health_check
  • PC External — http://<IP или имя сервера PC External>:8080/pc-client-api/health_check
  • PC Server Signer — http://<IP или имя сервера PC Server Signer>:8080/pc-server-signer-api/health_check

PC API

По умолчанию адрес сервера PCS для взаимодействия с его API располагается по адресу http://<host>:8080/pc-api/.

Включение формирования имитовставки (при необходимости)

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

Установка модуля КриптоПро JCP

Добавление модуля в WildFly

Можно установить двумя способами:

  • путём копирования загруженных файлов модуля и добавления описания модуля в файл конфигурации WildFly
  • с помощью jboss-cli

Имя модуля - ru.cryptopro.jcp

Файлы модуля доступны по ссылке https://repo.paycontrol.org/cdn/artefacts/wildfly/wf-module-ru.cryptoro.jcp.zip

Путём ручного копирования
  • Скопировать файлы из загруженного архива в wildfly/modules/ru/cryptopro/jcp/main
  • В файл wildfly/standalone/configuration/standalone.xml в тег subsystem xmlns="urn:jboss:domain:ee:[version] нужно добавить глобальную область видимости этого модуля путём добавления
<global-modules>
   <module name="ru.cryptopro.jcp" slot="main"/>
</global-modules>

Пример секции:

<subsystem xmlns="urn:jboss:domain:ee:6.0">
    <global-modules>
        <module name="ru.cryptopro.jcp" slot="main"/>
    </global-modules>
    ...
</subsystem>
С помощью jboss-cli
  • Распаковать архив wf-module-ru.cryptoro.jcp.zip
  • Перейти в распакованную папку main
  • Выполнить следующие команды:
sudo /opt/wildfly/bin/jboss-cli.sh -c --command="module add --name=ru.cryptopro.jcp --resources=ASN1P-2.0.41940.jar:JCP-2.0.41940.jar:JCryptoP-2.0.41940.jar:asn1rt-2.0.41940.jar"

sudo /opt/wildfly/bin/jboss-cli.sh -c --echo-command "/subsystem=ee:write-attribute(name=global-modules,value=[{name=ru.cryptopro.jcp, slot=main}])"

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

Создание временной директории для Linux

Необходимо создать "временную" директорию /var/opt/cprocsp/tmp с правом сервиса Wildfly на запись в неё.

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

В таблицу pc_sys_property внести настройку

-[ RECORD 1 ]-+-------------------
setting_id    | ...
setting_name  | GOST_IMIT_PROVIDER
setting_value | CryptoPro JCP 2.0

Описание внесения настроек в pc_sys_property доступно по ссылке.

Корректировка (смена) адресов компонентов серверов PC (при необходимости)

Учёт изменения адреса сервера PC Server

Для учёта изменения адреса PC Server необходимо произвести изменения в настройках PC External, указав правильный адрес и при необходимости порт сервера PC Server, а также уточнив протокол подключения (HTTP/HTTPS):

  • на Linux в файл WF_PATH/bin/standalone.conf в следующей строке:
JAVA_OPTS="$JAVA_OPTS -Dpc_url=http://<host>:<port>/pc-api/"
  • на Windows в файл WF_PATH\bin\standalone.conf.bat выше метки :JAVA_OPTS_SET в следующей строке:
set "JAVA_OPTS=%JAVA_OPTS% -Dpc_url=http://<host>:<port>/pc-api/"
  • под Docker, необходимо передать обновлённые данные через переменную окружения JAVA_OPTS :
- 'JAVA_OPTS=-Dpc_url=http://pc:8080/pc-api/'

Учёт изменения адреса сервера PC Pusher

Установить адрес PCP можно двумя способами:

запросом к API PCS

Изменить адрес для связи с компонентом PCP можно с помощью установки нового через API сервера PCS. Для этого необходимо отправить HTTP PATCH запрос с требуемым адресом PCP в качестве значения параметра pc_is_internal_url. Подробное описание PC API и эндпоинта для конфигурриования по ссылке. Пример тела запроса:

{
    "pc_is_internal_url":"http[s]://<HOSTNAME or IP>[:PORT]/pc-pusher-api/",
}

Этот способ является предпочитаемым.

SQL запросом к БД PCS

Для учёта изменения адреса сервера PC Pusher, необходимо, предварительно указав корректные данные (протокол (HTTP/HTTPS), имя или IP сервера, порт, идентификатор системы), выполнить запрос к БД PC Server:

update pc_system set pc_is_internal_url = 'http[s]://<IP или DNS-имя>[:PORT]/pc-pusher-api/' where systemid='<SYSTEMID>';

Приоритетным способом изменения параметров системы является установка параметров с помощью API. Работать с БД напрямую не рекомендуется.

Учёт изменения внешнего адреса сервера PC External

Адрес, используемый для связи мобильных приложений с серверной частью PC можно задать двумя способами: через API и в БД.

Для учёта изменения внешнего адреса сервера PC, по которому связываются мобильное приложение с сервером PC, необходимо, предварительно указав корректные данные (протокол (HTTP/HTTPS), имя или IP сервера, порт, идентификатор системы), выполнить запрос к БД PC Server:

update pc_system set pc_is_external_url = 'http[s]://<IP или DNS-имя>[:PORT]/pc-client-api/' where systemid='<SYSTEMID>';