GBS Web Apps Setup

Introduction

This manual describes the installation and update procedures for Griaule Servers for Web Applications.

Before starting, make sure some files are available on the target machine:

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

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

• Application 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;

• Python setup helper script updatescript.py;

• Pre-Setup scripts: setup_webapps.sh and, optionally, setup_aliases.sh if you want to create Aliases.

If any file is missing, contact Griaule Support Team at [email protected].

To perform a new installation, follow the steps:

1. Check if your system meets the Pre-Requisites

2. Run the Pre-setup scripts

3. Install the application

4. Configure the application

5. Verify if the application is running using the commands presented in Handling Applications

To update an application, follow the steps:

1. Check if your system meets the new version Pre-Requisites

2. Update the application through the presented commands

3. Check the Configurations

4. Verify if the application is running using the commands presented in Handling Applications

Pre-Requisites

• 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 (for ETR only);

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

• SmartSense Agent (for SmartSense only)

• CUPS (for Print only)

To learn more about the products of Griaule Biometric Suite (GBS), please refer to GBS Overview.

Pre-Setup

Some steps need to be performed before the installation process.

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

yum install tomcat -y

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

First, make sure that the Tomcats package (tomcats-v7.tar file) 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 not performing a fresh installation of all applications, DO NOT extract the tomcats-v7.tar package in the /var/lib/tomcats/ directory (Step 1). Instead, extract the package in a temporary directory and move only the folder of the application being installed to the /var/lib/tomcats/ directory. Then, proceed to Step 2.

Step 1: Transfer and unzip the tomcats-v7.tar package in the /var/lib/tomcats directory.

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

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

To perform this procedure, run the pre-installation script passing the name of the application being installed:

./setup_webapps.sh <app_name>

Step 3: Configure the aliases (optional).

Optionally, if you'd like to create aliases to ease application handling, run the following script:

./setup_aliases.sh <app_name>

Then, source the .bashrc file:

source ~/.bashrc

These scripts will:

• Create tomcat symlinks for each service

• Update/modify tomcat server scripts

• Add aliases to ease application handling

After those steps, if 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 it is already set, skip this step.

Then, proceed to the Installation procedures.

Installation

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

In all commands, remember to substitute <app_name> to the desired application name and to the corresponding version. The <app_name> 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 home directory:

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

Step 2: Change to the application webapps directory:

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

Step 3: Create a symlink in webapps 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 folder to the tomcat user:

chown -R tomcat:tomcat tomcats/

Then, proceed with the application Configurations.

Update

To update an application, proceed with the following steps:

In all commands, remember to substitute <app_name> to the desired application name and to the corresponding version. The <app_name> 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 old files:

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

Step 3: Move the application .war file to the application home directory:

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

Step 4: Change to the application webapps directory:

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

Step 5: Create a symlink in webapps 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 6: Run the database upgrade dumps, if the release includes them:

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

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

Step 7: Start the application:

systemctl start tomcat@<app_name>.service

Step 8: Change to the tomcats directory:

cd /var/lib/tomcats

Step 9: And run the setup script:

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

Configurations

Each component has its individual configuration. Those are presented in their respective manual (see links below).

In all commands, remember to substitute <app_name> to the desired application name and to the corresponding version. The <app_name> 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 app-specific database dump script 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 config.properties file:

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

To understand the configuration procedures, refer to each application 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

• Smart Sense Server Configuration Manual

• Control Panel Web Server Configuration Manual

• Print Server Configuration Manual

• Home Screen Server Configuration Manual

Make sure that the Connector port=<port_number> configuration parameter is correctly specified in the server.xml file, located at /var/lib/tomcats/<app_name>/conf. Please refer to the applications specific configuration manuals for further details. The connection (Connector port=<port_number>) and shutdown (Server port=... shutdown=...) ports should not be the same as each other or coincide with ports used by other applications.

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

Step 3: Next, access 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 tomcats directory:

cd /var/lib/tomcats

Step 8: Finally, if it's the first time running the application, run the setup script:

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

If installing SmartSense, make sure that ELK is also installed. For further instructions, refer to Elastic Stack (ELK) Installation Manual.

Handling Applications

This section shows some commands to monitor and handle Griaule services and their respective aliases.

Aliases

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

If not using the setup_aliases.sh script as described in Pre-Setup, it is possible to manually add the aliases. To do so, edit the root .bashrc 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 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 alias:

etrstart
csstart
beststart
intelstart
mirstart
bccstart
cpstart
smartstart
printstart
homestart

• Stop 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 alias:

etrstop
csstop
beststop
intelstop
mirstop
bccstop
cpstop
smartstop
printstop
homestop

• Check 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 alias:

etrstatus
csstatus
beststatus
intelstatus
mirstatus
bccstatus
cpstatus
smartstatus
printstatus
homestatus

• Check 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 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