> For the complete documentation index, see [llms.txt](https://docs.facephi.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.facephi.com/docs.facephi-en/sdks/backend-sdk/selphid/installation/installation_instructions.md).
# SDK installation and deployment
## 1. Introduction
This document includes the description of the components provided in the product **FacePhi SelphID SDK**.
This product includes several libraries whose API makes it possible to incorporate into your biometric authentication and identification solutions features that use images and/or facial templates, passive liveness checks, data validation, and extraction of information from identity documents.
The provided components and the steps required to install the SDK on the operating systems are detailed below **Windows** and **Linux**.
## 2. Contents of SelphID SDK
The Software Development Kit, **FacePhi SelphID SDK**, contains a set of libraries available for the Java, .NET, and C++ programming languages that allow the developer to integrate the main features offered by this product:
* Reading and validating digital identity document information (OCR).
* Authentication (1:1) and Identification (1:N) of users through Facial Recognition, using images or templates.
* Passive liveness checks of the user through images (without requiring user cooperation).
The content of **SelphID SDK** is as follows:
* Libraries in the C++, Java, and .NET programming languages (.NET only in the Windows version).
* Documentation for the Java API and .NET API, both in HTML format, with information on all supported methods in each class.
* Configuration file for the product License and usage and log files.
* Web services programming example in .NET/Java.
* C++ header files.
Different products are provided for the Windows and Linux operating systems.
* Products available for Windows.
* **fphi-selphid-sdk-win64\_x.x.x.x** (Windows 64-bit).
* Products available for Linux.
* **fphi-selphid-sdk-linux64\_x.x.x.x** (Linux distributions based on Ubuntu).
{% hint style="info" %}
**x.x.x.x** may vary, and corresponds to the product Version provided by **FacePhi**.
{% endhint %}
## 3. SDK Installation
This chapter describes the steps to install SelphID SDK.
### 3.1 Installation of the Software Development Kit
SelphID SDK is installed by extracting the provided contents into a directory on your system. The recommended directories are as follows:
* Recommended installation directories on Windows: **C:\\\Program Files\\\FacePhi\\\Sdk\\\SelphId\\\x.x.x.x**
* To unpack the Windows SDK, simply unzip the zip file to the indicated path.
* Recommended installation directories on Linux: **/opt/facephi/sdk/selphid/x.x.x.x**
* To unpack the Linux SDK, it is essential to do so on the same Linux server where the symbolic links are created. To do so, use the following command:
```bash
$ tar -xvzf fphi-selphid-sdk-linux64-x.x.x.x.tar.gz
```
{% hint style="info" %}
where "x.x.x.x" is the product version supplied by FacePhi.
{% endhint %}
{% hint style="warning" %}
After installation, the following folders should appear in the selected directory:
* API: Contains the programming API description.
* Bin: Contains the binary files.
* Windows: Runtime libraries and applications.
* Linux: Applications.
* Config: Contains the configuration files.
* Data: Contains the data files needed for correct runtime operation.
* Doc: Contains the EULA documentation and the SDK version file.
* Examples: Contains programming examples.
* Lib: Contains the files and libraries needed for compilation processes.
{% endhint %}
### 3.2 SDK Configuration
For the libraries included in the SDK to be available on the system, it is necessary to carry out the actions described below:
* **Create the FACEPHI\_SELPHID\_INSTALL\_PATH environment variable**
The value of this environment variable must contain the installation directory selected in the [previous point 3.1](#31-instalación-del-software-development-kit).
```bash
# Windows
set FACEPHI_SELPHID_INSTALL_PATH=C:\\Program Files\\FacePhi\\Sdk\\SelphId\\x.x.x.x
```
```bash
# Linux
export FACEPHI_SELPHID_INSTALL_PATH=/opt/facephi/sdk/selphid/x.x.x.x
```
* **Add the libraries directory to the PATH environment variable**
Once the above environment variable has been created, include the SDK's "bin" directory (for Windows) or "lib/lib" (for Linux) in the environment variable `PATH` (Windows) or `LD_LIBRARY_PATH` (Linux) of the system:
```bash
# Windows
set PATH=%PATH%;%FACEPHI_SELPHID_INSTALL_PATH%\\bin
```
```bash
# Linux
export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$FACEPHI_SELPHID_INSTALL_PATH/lib/lib
```
### 3.3 Environment variables
Different environment variables can be set to configure SDK operation:
* `FACEPHI_SELPHID_FACIAL_LICPATH_KEY` (required). Path to the file `license.lic`. Eg. `/opt/facephi/sdk/selphid/x.x.x.x/config/license.lic`.
* `FACEPHI_SELPHID_DEBUGPATH_KEY` (required). Path to the file where the log will be written. Eg. `/opt/facephi/sdk/selphid/x.x.x.x/config/selphidDebug.log`.
* `FACEPHI_SELPHID_USAGEPATH_KEY` (required). Path where the usage data file will be stored. Eg. `/opt/facephi/sdk/selphid/x.x.x.x/config/selphidUsage.db`.
* `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY` (required). Path to the folder `/data` in your local file system. Eg. `/opt/facephi/sdk/selphid/x.x.x.x/data`.
* `FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD` (optional). Similarity value 0-100 to determine whether an authentication is positive or negative. Default `65`.
* `FACEPHI_SELPHID_FACIALLIVENESS_THRESHOLD` (optional). Threshold 0-100 to determine whether a liveness operation is positive (Live) or negative (NoLive). Default `50`.
* `FACEPHI_SELPHID_FACIALEXTRACTOR_NUM_THREADS` (optional) 1-8 Number of threads (cores) assigned to extraction and authentication operations. Default `4`.
* `FACEPHI_SELPHID_FACIALLIVENESS_NUM_THREADS` (optional) 1-8 Number of threads (cores) assigned to liveness operations. Default `4`.
* `FACEPHI_SELPHID_FACIALLIVENESS_IAD` (optional) (`enable` or `disable`) Enables the filters for `Injection Attack Detection` for liveness operations. Default `enable`.
* `FACEPHI_SELPHID_FACIALLIVENESS_DEPTH` (optional) (`partial` or `full`) Specifies the depth of the liveness checks: `partial` (FPAD *Presentation Attack Detection*), `full` (FPAD + FMAD *Manipulation Attack Detection*). Default `partial`.
* `FACEPHI_SELPHID_GALLERY_REMOVE_METHOD` (optional) (`erase` or `noerase`) Specifies whether gallery items will be completely deleted using `SelphIDIdentifier::RemoveWithGalleryIndex()` or will be marked as invalid without being deleted. Default `erase`.
* `FACEPHI_SELPHID_FUTURE_TIME_ALLOWED` (optional) 0-N Specifies the time in seconds for which a Token with a future date will be valid. This is a global value that can be overridden per operation through `SelphIDVerifierOptions::SetFutureTimeAllowed()`. Default 0, which means that all tokens with a future date will be rejected.
## 4. SDK Licensing
To license the SelphID SDK product, it is necessary to carry out the actions described below:
### 4.1 Generation of machine identifiers
Machine identifiers can be obtained using a terminal and running the following command in the directory where the utility is located: `FACEPHI_SELPHID_INSTALL_PATH\\bin` (both on Windows and Linux)
{% hint style="warning" %}
Starting from version `6.20.0`, `selphid-license-activator` it runs as a standalone application, without needing to configure environment variables and without depending on SelphID-SDK.
{% endhint %}
```bash
# Windows ( selphid-license-activator.exe )
cd C:\\Program Files\\FacePhi\\Sdk\\SelphId\\x.x.x.x\\bin
selphid-license-activator.exe -hostid SN > hostid.txt
```
```bash
# Linux ( selphid-license-activator.sh )
$ cd /opt/facephi/sdk/selphid/x.x.x.x/bin
$ ./selphid-license-activator -hostid SN > hostid.txt
```
{% hint style="warning" %}
SN is the serial number of the License to be activated and provided by your license provider.
The format of the serial number "SN" is XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX.
Example with the above serial number:
```bash
# Windows ( selphid-license-activator.exe )
selphid-license-activator.exe -hostid XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX > hostid.txt
```
```bash
# Linux ( selphid-license-activator.sh )
$ ./selphid-license-activator -hostid XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX-XXXXXX > hostid.txt
```
{% endhint %}
{% hint style="warning" %}
Starting from version `6.15.0`, licensing based on the MAC addresses of network interfaces is enabled. In these cases, the MAC addresses of the interfaces involved in the licensing must be declared using the parameter `-addr`.
```bash
# Windows ( selphid-license-activator.exe )
selphid-license-activator.exe -hostid HOSTID -addr "74:04:F1:60:EE:A7" -addr "9C:2D:CD:E8:2A:E5" hostid.txt
```
```bash
# Linux ( selphid-license-activator.sh )
$ ./selphid-license-activator -hostid HOSTID -addr "00:15:5D:01:8C:01" > hostid.txt
```
{% endhint %}
Once the machine identifiers have been obtained, the file **hostid.txt** must be sent to your license provider so that your License can be generated (file with the .lic extension).
{% hint style="warning" %}
Starting with version 6.2.0, there is the possibility of **online activation** of the License. In this case, the license provider will provide you with a file `.lic` without needing to generate machine identifiers (it is not necessary to run `selphid-license-activator`).
{% endhint %}
### 4.2 License installation
The steps required to install the License are described below:
* **Copy the License into the config directory**
To install the License, simply copy the file `license.lic` that you receive from your distributor into the directory `config` located in the SDK installation path: `FACEPHI_SELPHID_INSTALL_PATH\\config`
* **Configure the License in the selphid.cfg file**
Once the license file has been copied, set the value of the variable contained in the file **selphid.cfg** to the value of the path where the License is located:
```
# Windows
FACEPHI_SELPHID_FACIAL_LICPATH_KEY=C:\\Program Files\\FacePhi\\Sdk\\SelphId\\x.x.x.x\\config\\license.lic
```
```
# Linux
FACEPHI_SELPHID_FACIAL_LICPATH_KEY=/opt/facephi/sdk/selphid/x.x.x.x/config/license.lic
```
{% hint style="info" %}
The directory `config` is the default directory for installing the License, although it is possible to install the License in another directory on the server. Simply, that directory will need to be reflected in the configuration file.
{% endhint %}
{% hint style="warning" %}
It is essential to verify that the values of the following variables are correctly configured with paths that exist on the operating system:
* FACEPHI\_SELPHID\_FACIAL\_LICPATH\_KEY: Path to the file `license.lic`.
* FACEPHI\_SELPHID\_FACIALLIVENESS\_PATH\_KEY: Path to the folder `/data` of the SelphID installation. Required for passive liveness checks.
* FACEPHI\_SELPHID\_USAGEPATH\_KEY: Path to the file where usage statistics are stored.
* FACEPHI\_SELPHID\_DEBUGPATH\_KEY: Path to the file where debugging information is stored. If omitted, no debugging information will be generated.
Likewise, it is necessary to check the expiration date of the License (it is found within the license file, in the "dateEnd" field) to ensure that the License is valid and has not expired.
{% endhint %}
### 4.3 Installation of the license service
The SelphID SDK license server is a terminal application that runs on Windows or Linux.
This application allows SelphID licenses to be served to client nodes without a static hostID. However, this server must run on a machine that has both **hostID** as well as a service port **TCP/UDP** static.
Requirements:
* Hardware:
* Static hostID
* Static port
* Software:
* SelphID SDK
* **Running the license service in a Linux terminal**
Steps to run the license service in a user terminal in Linux:
1. Unzip SelphID SDK. Example:
```bash
$ /opt/fphi-selphid-sdk-linux64_X.X.X
```
2. Copy the server License to the server directory with permissions `rw`. Example:
```bash
$ /opt/facephi/fphi-selphid-sdk-linux64_X.X.X/bin
```
3. Export the SelphID SDK library path to `LD_LIBRARY_PATH`. Example:
```bash
$ export \\
LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/opt/facephi/fphi-selphid-sdk-linux64_X.X.X/lib/lib/
```
4. Run the license service application indicating the port (-port), the path to the server license file (-lic), and optionally the license service log path (-log).
The license server must be started in administrator mode.
$ sudo LD_LIBRARY_PATH="$LD_LIBRARY_PATH" ./selphid-license-server -lic license-server.lic -port 15000
The parameter -log will refer to a directory and not to a file. This is due to the log rotation implementation.
In the case of the online activation, the server will start the first time without the file .lic requires updates.