# Installation of GBS Web Apps

## 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](#pre-instalacao): `setup_webapps.sh` and, optionally, `setup_aliases.sh` if you want to create [Aliases](#manuseando-as-aplicacoes).

{% hint style="warning" %}
If any file is missing, contact the Griaule Support Team by email: <support@griaule.com>.
{% endhint %}

To perform a new installation, follow these steps:

1. Check whether your system meets the [Prerequisites](#pre-requisitos)
2. Perform the [Pre-Installation](#pre-instalacao) using the script
3. [Install](#instalacao) the application
4. [Configure](#configuracoes) the application
5. Check whether the application is running using the commands presented in [Handling the Applications](#manuseando-as-aplicacoes)

To update an application, follow these steps:

1. Check whether your system meets the [Prerequisites](#pre-requisitos) of the new version
2. [Update](#atualizacao) the application using the presented commands
3. Check the [Logout.](#configuracoes)
4. Check whether the application is running using the commands presented in [Handling the Applications](#manuseando-as-aplicacoes)

## 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](/gbs/en/applications/etrweb.md));
* [Google Tesseract OCR Engine 4.0.0 or higher](https://github.com/tesseract-ocr/tesseract/releases) (only for the [CardScan](/gbs/en/applications/cardscanweb.md));
* [SmartSense Agent](/gbs/en/gbds-installation/smartsenseagent.md) (only for the [SmartSense](/gbs/en/applications/smartsense.md))
* [CUPS](/gbs/en/web-components/printconfig.md#sistemas-de-impressao) (only for the [Print](/gbs/en/applications/print.md))

{% hint style="info" %}
To learn more about the Griaule Biometric Suite (GBS) products, see [GBS Overview](/gbs/en/overview/readme.md).
{% endhint %}

## Pre-Installation

Some steps need to be performed before the installation process.

{% hint style="info" %}
If Tomcat is not installed, install it with the following command:

```sh
yum install tomcat -y
```

{% endhint %}

{% hint style="success" %}
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`.
{% endhint %}

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

{% hint style="info" %}
The `tomcats-v7.tar` package contains one folder for each application. The folder structure is as follows:

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

Each folder contains the following subfolders:

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

{% endhint %}

{% hint style="danger" %}
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**.
{% endhint %}

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

```sh
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:

```sh
./setup_webapps.sh <app_name>
```

**Step 3:** Configure aliases (optional).

Optionally, if you want to create [aliases](#manuseando-as-aplicacoes) to make application handling easier, run the following script:

```sh
./setup_aliases.sh <app_name>
```

Then, apply the `.bashrc`:

```sh
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

{% hint style="info" %}
After these steps, if the Cardscan Server and/or ETR are being installed, follow the steps below.

Open the database configuration file:

```sh
vim /etc/my.cnf
```

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

```properties
# CARDSCAN Required
max_allowed_packet=500M
```

If ETR is being installed, add the following line:

```properties
# ETR Required
sql-mode=""
```

If already configured, skip this step.
{% endhint %}

After completing the procedures above, proceed to [Installation](#instalacao).

## Installation

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

{% hint style="success" %}
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`.
{% endhint %}

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

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

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

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

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

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

**Step 4:** Change directory:

```sh
cd /var/lib/
```

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

```sh
chown -R tomcat:tomcat tomcats/
```

Then, proceed with the [Logout.](#configuracoes) file.

## Update

To update an application, proceed with the following steps:

{% hint style="success" %}
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`.
{% endhint %}

**Step 1:** Stop the application:

```sh
systemctl stop tomcat@<app_name>.service
```

**Step 2:** Remove the old files:

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

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

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

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

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

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

```sh
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:

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

{% hint style="success" %}
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.
{% endhint %}

**Step 7:** Start the application:

```sh
systemctl start tomcat@<app_name>.service
```

**Step 8:** Change to the application's `tomcats`:

```sh
cd /var/lib/tomcats
```

**Step 9:** Run the setup script:

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

## Logout.

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

{% hint style="success" %}
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`.
{% endhint %}

**Step 1:** Run the database dump:

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

{% hint style="success" %}
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.
{% endhint %}

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

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

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

* [BCC Web Server Configuration Manual](/gbs/en/web-components/bccwebconfig.md)
* [Cardscan Web Server Configuration Manual](/gbs/en/web-components/cardscanwebconfig.md)
* [ETR Web Server Configuration Manual](/gbs/en/web-components/etrwebconfig.md)
* [MIR Web Server Configuration Manual](/gbs/en/web-components/mirwebconfig.md)
* [BEST Web Server Configuration Manual](/gbs/en/web-components/bestwebconfig.md)
* [Intelligence Web Server Configuration Manual](/gbs/en/web-components/intelligencewebconfig.md)
* [SmartSense Server Configuration Manual](/gbs/en/web-components/smartsenseconfig.md)
* [Control Panel Web Server Configuration Manual](/gbs/en/web-components/controlpanelwebconfig.md)
* [Print Server Configuration Manual](/gbs/en/web-components/printconfig.md)
* [Home Screen Server Configuration Manual](/gbs/en/web-components/homescreenconfig.md)

{% hint style="info" %}
Make sure the configuration parameter `Connector port=<port_number>` is correctly specified in the `server.xml`file, 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.
{% endhint %}

{% hint style="info" %}
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**.
{% endhint %}

**Step 3:** Then, log into MySQL as root:

```sh
mysql -u root -p
```

**Step 4:** Run the following query:

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

**Step 5:** Exit MySQL:

```sql
exit
```

**Step 6:** Then, start the application.

```sh
systemctl start tomcat@<app_name>.service
```

**Step 7:** Change to the application's `tomcats`:

```sh
cd /var/lib/tomcats
```

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

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

{% hint style="warning" %}
If installing the **SmartSense**, make sure the **ELK** is also installed. For more instructions, consult the [Elastic Stack (ELK) Installation Manual](/gbs/en/auxiliary-tools/elk.md).
{% endhint %}

## 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.sh`script, as described in [Pre-Installation](#pre-instalacao), you can add the aliases manually. To do this, edit the `.bashrc` root file:

```sh
vim ~/.bashrc
```

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

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

### Useful Commands

* **Start the Application**

```sh
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 the alias:

```sh
etrstart
csstart
beststart
intelstart
mirstart
bccstart
cpstart
smartstart
printstart
homestart
```

* **Stop the Application**

```sh
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 the alias:

```sh
etrstop
csstop
beststop
intelstop
mirstop
bccstop
cpstop
smartstop
printstop
homestop
```

* **Check the Application Status**

```sh
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 the alias:

```sh
etrstatus
csstatus
beststatus
intelstatus
mirstatus
bccstatus
cpstatus
smartstatus
printstatus
homestatus
```

* **Check the Application Logs**

```sh
# 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:

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

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.griaule.com/gbs/en/web-components/gbsappssetup.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.