> 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 a description of the components provided in the product **FacePhi SelphID SDK**.
This product incorporates several libraries whose API allows authentication and biometric identification solutions to include functionalities that use images and/or facial templates, passive liveness detection, data validation, and extraction of information from identity documents.
The components provided 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 developers to integrate the main functionalities offered by this product:
* Reading and validation of information from digital identity documents (OCR).
* Authentication (1:1) and Identification (1:N) of users using Facial Recognition, using images or templates.
* Passive liveness detection of the user using images (without requiring user collaboration).
The content of **SelphID SDK** is as follows:
* Libraries in the C++, Java and .Net programming languages (.Net only in the Windows version).
* Java API documentation and .Net API documentation, both in HTML format, with information about all the methods supported in each of the classes.
* 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** (Ubuntu-based Linux distributions).
{% 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 unpacking the provided content into a directory on your system. The recommended directories are the following:
* Recommended installation directories on Windows: **C:\Program Files\FacePhi\Sdk\SelphId\x.x.x.x**
* To unpack the Windows SDK, it is only necessary to unzip it into 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 this, 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 the build processes.
{% endhint %}
### 3.2 SDK Configuration
To make the libraries included in the SDK available on the system, it is necessary to perform the actions described below:
* **Create the FACEPHI\_SELPHID\_INSTALL\_PATH environment variable**
The value of this environment variable must contain the selected installation directory 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 library directory to the PATH environment variable**
Once the previous 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 the SDK's operation:
* `FACEPHI_SELPHID_FACIAL_LICPATH_KEY` (required). Path to the file `license.lic`. For example `/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. For example `/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. For example `/opt/facephi/sdk/selphid/x.x.x.x/config/selphidUsage.db`.
* `FACEPHI_SELPHID_FACIALLIVENESS_PATH_KEY` (required). Path to the folder `/data` on your local file system. For example `/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 `Inyection 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 the gallery items will be completely removed through `SelphIDIdentifier::RemoveWithGalleryIndex()` or marked as invalid without being removed. Default `erase`.
* `FACEPHI_SELPHID_FUTURE_TIME_ALLOWED` (optional) 0-N Specifies the time in seconds during which a token with a future date will be valid. This is a global value that can be overridden per operation using `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 perform the actions described below:
### 4.1 Machine identifier generation
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 is provided by your licensing 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 the 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 **hostid.txt** file must be sent to your licensing provider so that your license can be generated (file with .lic extension).
{% hint style="warning" %}
Starting from version 6.2.0, there is the possibility of **online activation** of the license. In this case, the licensing provider will provide you with a `.lic` file without needing to generate machine identifiers (it is not necessary to run `selphid-license-activator`).
{% endhint %}
### 4.2 License installation
The steps necessary for license installation are described below:
* **Copy the license to the config directory**
To install the license, simply copy the file `license.lic` that you will 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 **selphid.cfg** file 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, you will need to reflect that directory 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 in 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 detection.
* 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, debugging information will not be generated.
Likewise, it is necessary to check the license expiration date (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 serving SelphID licenses to client nodes without static hostID. However, this server must run on a machine that has both **hostID** and 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. Unpack 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 path to the license service log (-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 requiring updates.