This document includes the next methods of PC deploying:

with installation script
in Docker containerisation environmrnt.

Before installation

DB preparing

PC supports the next DBMS: Postgres, Oracle, MS SQL.

Before installation is must to create PCS database and PCSS database (in case if Server Signer component will be installed).

Create database user with CRUD + Alter access privileges, whoose credentials will be used by PC to connect to created databases.

You should not to create any database structure. PC will create it automatically.

Java

For installation options "With installation script" and "Manual" you must install latest version of JRE 11.

With installation script

Installation script could deploy PC on Linux-based servers automatically.

Installation script help page

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

Installator configuring

Before installation you should to configure installer for automatically PC components configuring. To config installer you must edit CUSTOMER Config section of install.conf file. Set desired values for next params:

credentials to connect to PCS database;
credentials to connect to PCSS database;
PCS component address. It will used by PC External to connect to PC Server.

Oracle DB

Installation specificities with Oracle DB are given below.

SID/Service Name

In case of using Oracle DB you should specify, which method will be used to connect to DB - with SID or Service Name.

Driver version

OJDBC version	Supported Java and Oracle DB version by driver
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

Source — https://www.oracle.com/database/technologies/faq-jdbc.html#01_02.

Configuration file example

###################################################
#
# 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'

Installation

For installation you must use root or root-level privileged account.

Download installation pack to target server, for instance, to home directory.
Unpack it:
```
tar -xzvf pc-distrib-5.X.XXX.tar.gz
```
Switch current directory to just unpacked.
In case, if you have register system request file you may put it to customer directory for automatically register your application system in PC. Register system request file have name in the form RegisterSystemRequest 5.1 [company_name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx].json.
Execute installation script with root/sudo privileges with desired params.

Installation script running results

Installation script running results are:

WildFlу applications server installed (/opt directory);
service wildfly added with autostart enabled;
database drivers added (optionally);
datasources added (only for PC Server и PC Server Signer, if required);
PC modules deployed in WildFly;
application system registered in PC (in case if r option and register system request provided).

As a result of a application system registration - at the end of installation log in terminal system identifier will be shown (system_id).

Example:

    {
        "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
}

In this example registered system id is e64a67c9-73e9-462c-9c27-2d0195a2bd23. In the future this identifier may be needed for application system set up for communication with PC. If you loose this identifier, contact with vendor (Airome) to find out your ID.

Installer execution params examples

There few examples below, all of them, for install PC with PostgreSQL database driver (p option).

All in one server (test scheme)

Without application system registration
```
sudo ./install.sh -ipSPEG
```
With application system registration
```
  sudo ./install.sh -ipSPEGr
```

PC Server

Without application system registration
```
sudo ./install.sh -ipS
```
With application system registration
```
sudo ./install.sh -ipSr
```

PC External

sudo ./install.sh -iE

PC Server Signer

sudo ./install.sh -ipG

Monitoring

Follow logs in terminal

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

Checking installation success

ls -la /opt/pc/deployments/

In the case of successfull component deployment, there file with extention .deployed will be created. Name of the file will be the same as name of component (except extention).

Docker

Images

Images suppors PC from 3.5 version. They stored at hub.docker.com:

secrius/pc_wildfly:v5-pgsql
secrius/pc_wildfly:v5-oracle8
secrius/pc_wildfly:v5-oracle10
secrius/pc_wildfly:v5-oracle11
secrius/pc_wildfly:v5-mssql

In images for Oracle DB there added OJDBC driver version to the image tag. Use table for choose compatible OJDBC driver for your Oracle DB version.

Preparing

Server components modules files placement

In according with choosen integration option scheme you need to place modules .ear/.war files in deployments directory of corresponding container. PCSS module SHOULD be deployed in the same with PCS module container, but it may be deployed in separate contained in case if PCSS container will have network interconnection with PCS, but setting up of this interconnection is out of scope of this guide.

Environment

Bind mounts:

deployments — directory for placement ear/war PC modules files. Read and write privileges for uid/gid 1000:1000 MUST be granted for this directory. PC modules files available by link https://repo.payconfirm.org/server/maven/tech/paycon/server/;
themes — only for PCE, in case if PC Mobile themes will be used;
log — used for write log files by WildFly;
pki — only for PCS, optionaly, in case of PKI on OpenSSL-base will be used.

Additional startup parameters for PCE (should be passed to container by JAVA_OPTS environment variable):

pc_url — PCS component address. Default value is http://localhost:8080/pc-api/;
pc_logRequests — swith up logging for HTTP requests . Default — false;
pc_locale — language for error messages text, which returns by PCE to mobile app. Available option — ru. Default value — en;
pc_themesPath — PC Mobile App themes publicating directory path. Default value — /opt/wildfly/pc_themes/;

Example

There is examples for Combined scheme where PCS, PCSS, PCP modules in the same container, and PCE in another below:

.env

All PCSS DB connections params are optional, and MUST be used in case if Server Signer module will be deployed.

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

Directory /opt/pc/pki/ SHOULD be binded only in case if PKI on OpenSSL-base option in use.
Directory /opt/jboss/wildfly/pc_themes/ binding is optional and SHOULD be used in case if PC Mobile App themes feature is in use.

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: "secrius/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: "secrius/pc_wildfly:v5-pgsql"

After installation

Check services availability

Each PC module has health check endpoint, which returns module name, it's version and API version:

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

As default PCS API endpoint located at http://<host>:8080/pc-api/.

PC components addresses changing (in case of necessary)

PCS module address correction

For taking into account new PC Server's address you need to set actual hostname and port (if needed), and specify HTTP/HTTPS protocol settings at PC External settings:

on Linux in file WF_PATH/bin/standalone.conf, in the string like at the example:

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

on Windows in file WF_PATH\bin\standalone.conf.bat above the label :JAVA_OPTS_SET in the next string:

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

for Docker, pass new setting in JAVA_OPTS environment variable:

- 'JAVA_OPTS=-Dpc_url=http://pc:8080/pc-api/'

PCP module address correction

PC Pusher address can be changed in two ways:

by API request

For set up a new address, send PATCH HTTP-request to {{pc-server-api}}/{{system_id}} with desired address as value for pc_is_internal_url value. More details by link. Example of request body:

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

It is recommended method.

by SQL request

For update address in DB directly, you need to make SQL request to PCS database, pc_system table, pc_is_internal_url column. Example:

update pc_system set pc_is_internal_url = 'http[s]://<HOSTNAME or IP>[:PORT]/pc-pusher-api/' where systemid='<SYSTEMID>';

This method is not recommended, and preffered is set params via API. Direct database modification is not recommended.

PCE module address correction (Mobile App requests address)

by API request

For set up a new address, send PATCH HTTP-request to {{pc-server-api}}/{{system_id}} with desired address as value for pc_is_external_url value. More details by link. Example of request body:

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

It is recommended method.

by SQL request

For update address in DB directly, you need to make SQL request to PCS database, pc_system table, pc_is_internal_url column. Example:

update pc_system set pc_is_external_url = 'http[s]://<HOSTNAME or IP>[:PORT]/pc-client-api/' where systemid='<SYSTEMID>';

This method is not recommended, and preffered is set params via API. Direct database modification is not recommended.

Installation PC version 5

Before installation

DB preparing

Java

With installation script

Installation script help page

Installator configuring

Oracle DB

SID/Service Name

Driver version

Configuration file example

Installation

Installation script running results

Installer execution params examples

All in one server (test scheme)

PC Server

PC External

PC Server Signer

Monitoring

Follow logs in terminal

Checking installation success

Docker

Images

Preparing

Server components modules files placement

Environment

Example

.env

docker-compose.yml

After installation

Check services availability

PC API

PC components addresses changing (in case of necessary)

PCS module address correction

PCP module address correction

by API request

by SQL request

PCE module address correction (Mobile App requests address)

by API request

by SQL request