1. 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.

Important

If any file is missing, contact Griaule Support Team at support@griaule.com.

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

2. Pre-Requisites

See also

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

3. Pre-Setup

Some steps need to be performed before the installation process.

Note

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

yum install tomcat -y

Tip

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

Note

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

Danger

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

Note

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.

4. Installation

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

Tip

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

5. Update

To update an application, proceed with the following steps:

Tip

In all commands, remember to substitute <app_name> to the desired application name and <version> 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

Tip

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>

6. Configurations

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

Tip

In all commands, remember to substitute <app_name> to the desired application name and <version> 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

Tip

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:

Note

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.

Note

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>

Important

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

7. Handling Applications

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

7.1. 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 tomcat@etr.service'
alias etrstop='systemctl stop tomcat@etr.service'
alias etrstatus='systemctl status tomcat@etr.service'
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 tomcat@cardscan.service'
alias csstop='systemctl stop tomcat@cardscan.service'
alias csstatus='systemctl status tomcat@cardscan.service'
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 tomcat@best.service'
alias beststop='systemctl stop tomcat@best.service'
alias beststatus='systemctl status tomcat@best.service'
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 tomcat@intelligence.service'
alias intelstop='systemctl stop tomcat@intelligence.service'
alias intelstatus='systemctl status tomcat@intelligence.service'
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 tomcat@mir.service'
alias mirstop='systemctl stop tomcat@mir.service'
alias mirstatus='systemctl status tomcat@mir.service'
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 tomcat@bcc.service'
alias bccstop='systemctl stop tomcat@bcc.service'
alias bccstatus='systemctl status tomcat@bcc.service'
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 tomcat@control-panel.service'
alias cpstop='systemctl stop tomcat@control-panel.service'
alias cpstatus='systemctl status tomcat@control-panel.service'
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 tomcat@smart-sense.service'
alias smartstop='systemctl stop tomcat@smart-sense.service'
alias smartstatus='systemctl status tomcat@smart-sense.service'
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 tomcat@print.service'
alias printstop='systemctl stop tomcat@print.service'
alias printstatus='systemctl status tomcat@print.service'
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 tomcat@home-screen.service'
alias homestop='systemctl stop tomcat@home-screen.service'
alias homestatus='systemctl status tomcat@home-screen.service'
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'

7.2. Useful Commands

  • Start Application
systemctl start tomcat@etr.service
systemctl start tomcat@cardscan.service
systemctl start tomcat@best.service
systemctl start tomcat@intelligence.service
systemctl start tomcat@mir.service
systemctl start tomcat@bcc.service
systemctl start tomcat@control-panel.service
systemctl start tomcat@smart-sense.service
systemctl start tomcat@print.service
systemctl start tomcat@home-screen.service

or with alias:

etrstart
csstart
beststart
intelstart
mirstart
bccstart
cpstart
smartstart
printstart
homestart
  • Stop Application
systemctl stop tomcat@etr.service
systemctl stop tomcat@cardscan.service
systemctl stop tomcat@best.service
systemctl stop tomcat@intelligence.service
systemctl stop tomcat@mir.service
systemctl stop tomcat@bcc.service
systemctl stop tomcat@control-panel.service
systemctl stop tomcat@smart-sense.service
systemctl stop tomcat@print.service
systemctl stop tomcat@home-screen.service

or with alias:

etrstop
csstop
beststop
intelstop
mirstop
bccstop
cpstop
smartstop
printstop
homestop
  • Check Application Status
systemctl status tomcat@etr.service
systemctl status tomcat@cardscan.service
systemctl status tomcat@best.service
systemctl status tomcat@intelligence.service
systemctl status tomcat@mir.service
systemctl status tomcat@bcc.service
systemctl status tomcat@control-panel.service
systemctl status tomcat@smart-sense.service
systemctl status tomcat@print.service
systemctl status tomcat@home-screen.service

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