GBS Web Apps Installation

Introduction

This manual describes the installation and update procedure of Griaule servers for Web Applications.

To perform the installation, some files need to be available on the machine where the application will be installed:

• Application .war file, gbs-<app_name>-web-server-<version>.war;

• Database dump script, clear-<app_name>-<DD>-<MM>-<YYYY>.sql, if installing;

• Database upgrade script, upgrade-<app_name>-<DD>-<MM>-<YYYY>.sql, if updating;

• Sphinx database script, clear-sphinx-<DD>-<MM>-<YYYY>.sql;

• Apache Tomcat package, tomcats-v7.tar;

• Setup script setup.sh;

• Helper Python script for configuration updatescript.py;

• Scripts for Pre-Installation: setup_webapps.sh and, optionally, setup_aliases.sh if you want to create Aliases.

If any file is missing, contact the Griaule Support Team by email: [email protected].

To perform a new installation, follow these steps:

1. Check whether your system meets the Prerequisites

2. Perform the Pre-Installation using the script

3. Install the application

4. Configure the application

5. Check whether the application is running using the commands presented in Handling the Applications

To update an application, follow these steps:

1. Check whether your system meets the Prerequisites of the new version

2. Update the application using the presented commands

3. Check the Logout.

4. Check whether the application is running using the commands presented in Handling the Applications

Prerequisites

• Linux (CentOS 7 / Red Hat 7 / Oracle Linux 7 / Oracle Linux 8);

• Java Development Kit version 1.8+;

• Apache: Tomcat version 7+;

• Database: MySQL/MariaDB 5.7+;

• libusb, libpng12, compat-libtiff3;

• GBDS: API;

• GBDS: Matcher;

• GBDS: Notifier (only for the ETR);

• Google Tesseract OCR Engine 4.0.0 or higher (only for the CardScan);

• SmartSense Agent (only for the SmartSense)

• CUPS (only for the Print)

To learn more about the Griaule Biometric Suite (GBS) products, see GBS Overview.

Pre-Installation

Some steps need to be performed before the installation process.

If Tomcat is not installed, install it with the following command:

yum install tomcat -y

In all commands, remember to replace <app_name> with the desired application name and also <version> with the corresponding version. The <app_name> it can be: bcc, cardscan, etr, mir, best, intelligence, smart-sense, print, control-panel or home-screen.

First, make sure the Tomcats package (file tomcats-v7.tar) provided is available on the machine where the application will be installed.

The tomcats-v7.tar package contains one folder for each application. The folder structure is as follows:

/var/lib/tomcats/
├── bcc
├── best
├── cardscan
├── control-panel
├── etr
├── home-screen
├── intelligence
├── mir
├── print
└── smart-sense

Each folder contains the following subfolders:

/var/lib/tomcats/<app_name>/
├── conf
├── logs
├── temp
├── webapps
└── work

If you are not performing a fresh installation of all applications, NOT extract the tomcats-v7.tar package into the /var/lib/tomcats/ directory (Step 1). Instead, extract the package into a temporary directory and move only the folder of the application being installed into the /var/lib/tomcats/directory. Then, continue to Step 2.

Step 1: Transfer and extract the tomcats-v7.tar package into the /var/lib/tomcats.

mkdir -p /var/lib/tomcats && tar -xf tomcats-v7.tar -C /var/lib/tomcats

Step 2: Perform the application pre-installation using the setup_webapps.sh provided script.

To perform this procedure, run the pre-installation script passing the name of the application you want to install:

./setup_webapps.sh <app_name>

Step 3: Configure aliases (optional).

Optionally, if you want to create aliases to make application handling easier, run the following script:

./setup_aliases.sh <app_name>

Then, apply the .bashrc:

source ~/.bashrc

These scripts will:

• Create symbolic links from tomcat for each service

• Update/modify tomcat server scripts

• Add aliases to make application handling easier

After these steps, if the Cardscan Server and/or ETR are being installed, follow the steps below.

Open the database configuration file:

vim /etc/my.cnf

Under [mysqld], if CardScan is being installed, add the following line:

# CARDSCAN Required
max_allowed_packet=500M

If ETR is being installed, add the following line:

# ETR Required
sql-mode=""

If already configured, skip this step.

After completing the procedures above, proceed to Installation.

Installation

Before starting the installation procedure, make sure the application .war file is available on the machine where the application will be installed.

In all commands, remember to replace <app_name> with the desired application name and also <version> with the corresponding version. The <app_name> it can be: bcc, cardscan, etr, mir, best, intelligence, smart-sense, print, control-panel or home-screen.

Step 1: Move the application .war file to the application's home directory:

mv *.war /var/lib/tomcats/<app_name>/

Step 2: Change to the application's webapps directory:

cd /var/lib/tomcats/<app_name>/webapps

Step 3: Create a symbolic link in the webapps directory to the application .war file.

ln -s /var/lib/tomcats/<app_name>/gbs-<app_name>-web-server-<version>.war gbs-<app_name>-server.war

Step 4: Change directory:

cd /var/lib/

Step 5: Change the ownership of the files in the tomcats directory to the user tomcat:

chown -R tomcat:tomcat tomcats/

Then, proceed with the Logout. file.

Update

To update an application, proceed with the following steps:

In all commands, remember to replace <app_name> with the desired application name and also <version> with the corresponding version. The <app_name> it can be: bcc, cardscan, etr, mir, best, intelligence, smart-sense, print, control-panel or home-screen.

Step 1: Stop the application:

systemctl stop tomcat@<app_name>.service

Step 2: Remove the old files:

sudo rm -rf /var/lib/tomcats/<app_name>/webapps/*

Step 3: Place the application .war file in the application's home directory:

mv *.war /var/lib/tomcats/<app_name>/

Step 4: Change to the application's webapps directory:

cd /var/lib/tomcats/<app_name>/webapps

Step 5: Create a symbolic link in the webapps directory to the application .war directory:

ln -s /var/lib/tomcats/<app_name>/gbs-<app_name>-web-server-<version>.war gbs-<app_name>-server.war

Step 6: Run the database upgrade dumps if the release includes them:

mysql -u root -p < <path/to/script>.sql

The application-specific script is usually called upgrade-<app_name>-<DD>-<MM>-<YYYY>.sql. There may be more than one script. In that case, run the other scripts as well.

Step 7: Start the application:

systemctl start tomcat@<app_name>.service

Step 8: Change to the application's tomcats:

cd /var/lib/tomcats

Step 9: Run the setup script:

/var/lib/tomcats/setup.sh <app_name>

Logout.

Each component has its individual configuration. These are presented in their respective manual.

In all commands, remember to replace <app_name> with the desired application name and also <version> with the corresponding version. The <app_name> it can be: bcc, cardscan, etr, mir, best, intelligence, smart-sense, print, control-panel or home-screen.

Step 1: Run the database dump:

mysql -u root -p < <path/to/script>.sql

The database dump script specific to each application is usually called clear-<app_name>-<DD>-<MM>-<YYYY>.sql. There may be another script, usually called clear-sphinx-<DD>-<MM>-<YYYY>.sql. In this case, run it as well.

Step 2: Then, edit the file config.properties:

vim /var/lib/tomcats/<app_name>/conf/config.properties

To understand the configuration procedures, consult the specific configuration manual:

• BCC Web Server Configuration Manual

• Cardscan Web Server Configuration Manual

• ETR Web Server Configuration Manual

• MIR Web Server Configuration Manual

• BEST Web Server Configuration Manual

• Intelligence Web Server Configuration Manual

• SmartSense Server Configuration Manual

• Control Panel Web Server Configuration Manual

• Print Server Configuration Manual

• Home Screen Server Configuration Manual

Make sure the configuration parameter Connector port=<port_number> is correctly specified in the server.xmlfile, located at /var/lib/tomcats/<app_name>/conf. For more information, consult the specific configuration manuals for each application. The connection (Connector port=<port_number>) and shutdown (Server port=... shutdown=...) ports must not be equal to each other or coincide with ports used by other applications.

Make sure the configuration parameters <app_name>.ip, <app_name>.port and <app_name>.protocol are correctly specified in the file config.properties. The IP address must match the one configured in the server.xml. In many cases, the IP will be the same for several applications. However, each application will have a different and unique port.

Step 3: Then, log into MySQL as root:

mysql -u root -p

Step 4: Run the following query:

SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));

Step 5: Exit MySQL:

exit

Step 6: Then, start the application.

systemctl start tomcat@<app_name>.service

Step 7: Change to the application's tomcats:

cd /var/lib/tomcats

Step 8: If it is the first time running the application, run the setup script:

/var/lib/tomcats/setup.sh <app_name>

If installing the SmartSense, make sure the ELK is also installed. For more instructions, consult the Elastic Stack (ELK) Installation Manual.

Handling the Applications

This section presents some commands to monitor and handle Griaule services, as well as their respective aliases.

Aliases

Aliases are short user-defined commands that serve as substitutes for longer or more complex commands. They are created to make frequently used commands more convenient to execute. When an alias is invoked, it is replaced by the full command it represents before being executed.

If you are not using the setup_aliases.shscript, as described in Pre-Installation, you can add the aliases manually. To do this, edit the .bashrc root file:

vim ~/.bashrc

And add the following aliases, according to the desired application:

# ETR
alias etrstart='systemctl start [email protected]'
alias etrstop='systemctl stop [email protected]'
alias etrstatus='systemctl status [email protected]'
alias etrhome='cd /var/lib/tomcats/etr'
alias etrconf='vim /var/lib/tomcats/etr/conf/config.properties'
alias etrsetup='/var/lib/tomcats/setup.sh'
alias etrlogt='journalctl -u tomcat@etr -f'
alias etrlog='journalctl -u tomcat@etr | less'

# CARDSCAN
alias csstart='systemctl start [email protected]'
alias csstop='systemctl stop [email protected]'
alias csstatus='systemctl status [email protected]'
alias cshome='cd /var/lib/tomcats/cardscan'
alias csconf='vim /var/lib/tomcats/cardscan/conf/config.properties'
alias cssetup='/var/lib/tomcats/setup.sh'
alias cslogt='journalctl -u tomcat@cardscan -f'
alias cslog='journalctl -u tomcat@cardscan | less'

# BEST
alias beststart='systemctl start [email protected]'
alias beststop='systemctl stop [email protected]'
alias beststatus='systemctl status [email protected]'
alias besthome='cd /var/lib/tomcats/best'
alias bestconf='vim /var/lib/tomcats/best/conf/config.properties'
alias bestsetup='/var/lib/tomcats/setup.sh'
alias bestlogt='journalctl -u tomcat@best -f'
alias bestlog='journalctl -u tomcat@best | less'

# INTELLIGENCE
alias intelstart='systemctl start [email protected]'
alias intelstop='systemctl stop [email protected]'
alias intelstatus='systemctl status [email protected]'
alias intelhome='cd /var/lib/tomcats/intelligence'
alias intelconf='vim /var/lib/tomcats/intelligence/conf/config.properties'
alias intelsetup='/var/lib/tomcats/setup.sh'
alias intellogt='journalctl -u tomcat@intelligence -f'
alias intellog='journalctl -u tomcat@intelligence | less'

# MIR
alias mirstart='systemctl start [email protected]'
alias mirstop='systemctl stop [email protected]'
alias mirstatus='systemctl status [email protected]'
alias mirhome='cd /var/lib/tomcats/mir'
alias mirconf='vim /var/lib/tomcats/mir/conf/config.properties'
alias mirsetup='/var/lib/tomcats/setup.sh'
alias mirlogt='journalctl -u tomcat@mir -f'
alias mirlog='journalctl -u tomcat@mir | less'

# BCC
alias bccstart='systemctl start [email protected]'
alias bccstop='systemctl stop [email protected]'
alias bccstatus='systemctl status [email protected]'
alias bcchome='cd /var/lib/tomcats/bcc'
alias bccconf='vim /var/lib/tomcats/bcc/conf/config.properties'
alias bccsetup='/var/lib/tomcats/setup.sh'
alias bcclogt='journalctl -u tomcat@bcc -f'
alias bcclog='journalctl -u tomcat@bcc | less'

# CONTROL PANEL
alias cpstart='systemctl start [email protected]'
alias cpstop='systemctl stop [email protected]'
alias cpstatus='systemctl status [email protected]'
alias cphome='cd /var/lib/tomcats/control-panel'
alias cpconf='vim /var/lib/tomcats/control-panel/conf/config.properties'
alias cpsetup='/var/lib/tomcats/setup.sh'
alias cplogt='journalctl -u tomcat@control-panel -f'
alias cplog='journalctl -u tomcat@control-panel | less'

# SMARTSENSE
alias smartstart='systemctl start [email protected]'
alias smartstop='systemctl stop [email protected]'
alias smartstatus='systemctl status [email protected]'
alias smarthome='cd /var/lib/tomcats/smart-sense'
alias smartconf='vim /var/lib/tomcats/smart-sense/conf/config.properties'
alias smartsetup='/var/lib/tomcats/setup.sh'
alias smartlogt='journalctl -u tomcat@smart-sense -f'
alias smartlog='journalctl -u tomcat@smart-sense | less'

# PRINT
alias printstart='systemctl start [email protected]'
alias printstop='systemctl stop [email protected]'
alias printstatus='systemctl status [email protected]'
alias printhome='cd /var/lib/tomcats/print'
alias printconf='vim /var/lib/tomcats/print/conf/config.properties'
alias printsetup='/var/lib/tomcats/setup.sh'
alias printlogt='journalctl -u tomcat@print -f'
alias printlog='journalctl -u tomcat@print | less'

# HOME SCREEN
alias homestart='systemctl start [email protected]'
alias homestop='systemctl stop [email protected]'
alias homestatus='systemctl status [email protected]'
alias homehome='cd /var/lib/tomcats/home-screen'
alias homeconf='vim /var/lib/tomcats/home-screen/conf/config.properties'
alias homesetup='/var/lib/tomcats/setup.sh'
alias homelogt='journalctl -u tomcat@home-screen -f'
alias homelog='journalctl -u tomcat@home-screen | less'

Useful Commands

• Start the Application

systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]
systemctl start [email protected]

or with the alias:

etrstart
csstart
beststart
intelstart
mirstart
bccstart
cpstart
smartstart
printstart
homestart

• Stop the Application

systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]
systemctl stop [email protected]

or with the alias:

etrstop
csstop
beststop
intelstop
mirstop
bccstop
cpstop
smartstop
printstop
homestop

• Check the Application Status

systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]
systemctl status [email protected]

or with the alias:

etrstatus
csstatus
beststatus
intelstatus
mirstatus
bccstatus
cpstatus
smartstatus
printstatus
homestatus

• Check the Application Logs

# tail log
journalctl -u tomcat@etr -f
journalctl -u tomcat@cardscan -f
journalctl -u tomcat@best -f
journalctl -u tomcat@intelligence -f
journalctl -u tomcat@mir -f
journalctl -u tomcat@bcc -f
journalctl -u tomcat@control-panel -f
journalctl -u tomcat@smart-sense -f
journalctl -u tomcat@print -f
journalctl -u tomcat@home-screen -f

# full log
journalctl -u tomcat@etr | less
journalctl -u tomcat@cardscan | less
journalctl -u tomcat@best | less
journalctl -u tomcat@intelligence | less
journalctl -u tomcat@mir | less
journalctl -u tomcat@bcc | less
journalctl -u tomcat@control-panel | less
journalctl -u tomcat@smart-sense | less
journalctl -u tomcat@print | less
journalctl -u tomcat@home-screen | less

or with the alias:

# tail log
etrlogt
cslogt
bestlogt
intellogt
mirlogt
bcclogt
cplogt
smartlogt
printlogt
homelogt

# full log
etrlog
cslog
bestlog
intellog
mirlog
bcclog
cplog
smartlog
printlog
homelog