Setting Up FaceTec Server

Learn how to set up and run the FaceTec Server.

If you are updating the FaceTec Server, please see Updating the FaceTec Server for details.


Testing with Postman

FaceTec recommends using Postman to test the APIs and created a Postman Test Suite that allows Customers & Partners to test against all of the Core FaceTec APIs.

  1. Download and Install Postman.
  2. Install simplehttpserver: npm install -g simplehttpserver .

Step 1: Run the FaceTec Server Locally

This step focuses on running the FaceTec Server on Your Dev Machine. As every step in the FaceTec Server Setup Guide relies on this step, completing this step before proceeding to the remainder of the guide is required.

System Requirements

Step 1 Instructions

  1. In Download SDKs, choose Server.
  2. In Database, choose “In-Memory Stub DB”.
  3. In Initialize For Postman Test Suite With Server, click "Yes" (necessary for Step 3).
  4. Download and Extract the FaceTec Server.
  5. Go to the Deployment Scripts Directory: cd FaceTec-Server-Webservice/Docker-Deployment-Scripts.
  6. Run the run.sh bash script: ./run.sh.
    Note: If Your Environment does not support Bash natively, then the Docker Compose Commands will need to be run manually instead:
    1. Run docker compose build facetec_server_webservice_prebuilt_with_usage_log_server facetec_usage_log_server.
    2. Run docker compose up facetec_server_webservice_prebuilt_with_usage_log_server facetec_usage_log_server.
  7. On success, http://localhost:8080/status will show a JSON Success Message.
Important Note: In some cases, Step 1 may output a 401 Error when using Docker on Windows. To resolve, you may need to remove Docker's configuration file (config.json) and clear its cache (buildx folder). This will clear your authentication details, which will force Docker to refresh your login credentials. For more information, please see FaceTec Server Docker Build Failing with 401 Error.

Step 2: Run the FaceTec Server Remotely

This step focuses on how to run the FaceTec Server on a Remote Machine. Unlike Step 1, this Step requires you to use the command line to securely copy the FaceTec Server and access Your Remote Server. As this step also covers important principles related to the Inbound/Outbound Network Configuration, understanding the instructions in this step before proceeding to the remainder of this guide is required.

System Requirements

Instructions

  1. Download the FaceTec Server (same as in Step 1) and rename the zip to ServerSDK.zip.
  2. Ensure you can SSH to Your Remote Linux Machine. (AWS EC2 Example)
  3. Configure Inbound/Outbound Network Traffic. (AWS EC2 Example)
  4. Copy the FaceTec Server to Your Remote Linux Machine:
    scp -i <SSH_KEY> ServerSDK.zip <USER>@<REMOTE_IP>:/home/<USER>.
  5. ssh into Your Remote Linux Machine:
    ssh -i <SSH_KEY> <USER>@<REMOTE_IP>.
  6. Install docker on Your Remote Linux Machine (via the command line).
  7. Unzip the FaceTec Server: unzip FaceTecServer.zip -d FaceTecServer.
  8. Go to the Deployment Scripts Directory: cd FaceTec-Server-Webservice/Docker-Deployment-Scripts.
  9. Run the run.sh bash script: ./run.sh.
  10. On success, http://<SERVER_IP_ADDRESS>:8080/status will show a JSON Success Message.
Using a Custom Port with your FaceTec Server Port: To change Your FaceTec Server's Default Port, you must edit the Dockerfile and docker-compose.yaml files located in Deployment-Scripts and replace the Default Port Value (8080) with the Custom Port of Your Choice.

Step 3: Test Local/Remote FaceTec Server with Postman

This step focuses on how to test the FaceTec Server with Postman. As this step requires a running instance of the FaceTec Server, completing Steps 1 and 2 is necessary before moving to this step. This step provides a simple means for Customers & Partners to determine if the APIs are working, and FaceTec recommends finishing this step before proceeding further in this guide.

  1. Launch the FaceTec Server using Step 1 or Step 2.
  2. Open a new terminal, go to the root of the FaceTec Postman Test Suite, and run simplehttpserver.
  3. Open Postman, and choose Your Workspace to import the FaceTec Postman Collection.
  4. Go to "Environments" and click localhost to open a table of environment variables.
  5. (Remote Server Only) For FACETEC_SERVER_BASE_URL, set both of its values to http://:8080.
    Example: For IP address 12.345.6789, it would be http://12.345.6789:8080.
  6. For DEVICE_KEY_IDENTIFIER, X_USER_AGENT_ANDROID, X_USER_AGENT_BROWSER, and X_USER_AGENT_IOS fields, replace INSERT_DEVICE_KEY_HERE with your Device Key.
  7. Press the "checkmark" on the localhost button to confirm these changes.
  8. In "Collections", go to the FaceTec Collection, click the "View more actions" button, and choose "Run Collection".
  9. Run the Test Suite by pressing "Run FaceTec Test Suite...".
  10. On success, all of the Postman Tests will run and succeed.

Step 4: Test the Server /status APIs

To test the FaceTec Server's /status API, run the following curl command from Your Development Machine:

curl <SERVER_IP_ADDRESS>:8080/status

If this curl commands fails to return a JSON Response, then there may be a Network Configuration Issue. Please ensure Your Inbound/Outbound Port Configuration Settings are correct.

Important Note: If you are using Amazon Web Services (AWS), please see AWS: Create an EC2 Instance for a full video walkthrough on how to configure an EC2 Instance for this step.

Step 5 (Optional): Configure Secure Sockets Layer (SSL) or Transport Layer Security (TLS) for the FaceTec Server

This step focuses on how to configure Secure Sockets Layer (SSL) or Transport Layer Security (TLS) for the FaceTec Server. Since Step 6 already ensures the configuration of SSL/TLS for Your Middle-Layer Web Service, Step 5 is optional and not required. However, if you want to send data to the FaceTec Server via Server-to-Server HTTPS API Calls (instead of HTTP API Calls), then you should follow the video and guide in this step.

To make HTTPS calls, you first need to establish a SSL/TLS Certificate. There are numerous ways to do this depending on Your Architecture and whether you are using a Cloud Provider.

On AWS, a SSL/TLS Certificate can be configured using a Classic Load Balancer and connecting it to Amazon Certificate Manager. The below video and guide show this process in more detail, which should be similar to the process needed for other Cloud Services.

Important Note: AWS is not required for this step and is only used for demonstration purposes. There are numerous other cloud environments and remote server options that can also be used. We recommend that you utilize what is best for your specific use case.

  1. Create a Target Group for the Load Balancer.
  2. Create a Security Group for the Load Balancer.
  3. Update the FaceTec Server's Security Group to allow Inbound Traffic from the Load Balancer on Port 8080.
  4. Create a Load Balancer with a SSL/TLS Certificate for the FaceTec Server.
  5. Create an HTTPS Alias for the Load Balancer.
  6. Verify SSL/TLS has been established by making HTTPS API Calls to the FaceTec Server.

Step 6: Make HTTPS Calls to the FaceTec Server via a Middle-Layer Web Service

This step focuses on how to communicate with the FaceTec Server via a Middle-Layer Web Service. In Your Real Production Environment, Your App Code is responsible for sending the FaceTec Device SDK Outputs (3D FaceScans, IDScans, Audit Images, etc.) to Your Web Service. Once Your Web Service receives this data, Your Backend Business Logic will handle the request and send the necessary data to the FaceTec Server via Server-to-Server API Calls*. The FaceTec Server then handles this request and only sends the necessary data back to Your Web Service, which then sends it to Your App Code.

The below video and guide show how to construct a Simple Web Service that does the above. Once you have finished this tutorial, you can apply the same core principles to the integration of Your Real Web Service.

Important Note: AWS is not required for this step and is only used for demonstration purposes. There are numerous other cloud environments and remote server options that can also be used. We recommend that you utilize what is best for your specific use case.

* The below video and guide have the Web Service making direct HTTP Calls to the FaceTec Server. If you want to send data using Server-to-Server HTTPS API Calls, then you will need to follow the instructions in Step 5 to configure Secure Sockets Layer (SSL) or Transport Layer Security (TSL) for the FaceTec Server.

  1. Create a Security Group for the Web Service with Outbound Traffic for the FaceTec Server and Inbound Traffic for a Remote Connection (via SSH).
  2. Create an AWS EC2 Instance for the Web Service.
  3. Create a Target Group for the Web Service's Load Balancer.
  4. Create a Security Group for the Web Service's Load Balancer.
  5. Create a Load Balancer with a SSL/TLS Certificate for the Web Service.
  6. Update the Web Service's Security Group to allow Inbound Traffic from the Load Balancer on Port 8080.

  7. Update the FaceTec Server's Security Group to allow Inbound Traffic from the Web Service on Port 8080

  8. Create an HTTPS Alias for the Web Service's Load Balancer.
  9. Create a Basic Web Service with a /status HTTPS API Interface.
  10. Update the Web Service to call and return the FaceTec Server's /status HTTPS API.
  11. Verify Your Development Machine can make HTTPS API calls to the FaceTec Server via the Web Service.

Step 7: Run the FaceTec Server with Your Chosen Database Technology

The previous steps utilize a Non-Persistent Stub Database in Ephemeral Memory. This configuration is primarily meant for Testing during the Development Phase and is not recommended in a Production Environment. This is since all 3D FaceMaps, ID Scans, Audit Trails, and Transaction Records are lost when the Server reboots or is powered off. Since this data is required for 3D Enrollment, 3D:3D Face Matching, and 3D:2D Matching, a Persisted Database outside of Ephemeral Memory should be configured for Your Production Environment.

Running the FaceTec Server with MongoDB

MongoDB is highly recommended and completely supported. MongoDB provides a simple, yet effective, means of storing and managing Your Data. To learn how to use MongoDB, see Database - Useful Queries, Metrics, & Benchmarks.

  1. Set up MongoDB.
  2. In Download the FaceTec SDKs, choose FaceTec Server .
  3. Click “Download the SDK”.
  4. In the Database, choose “MongoDB”.
  5. Download and Extract the FaceTec Server.
  6. In the FaceTec Server Webservice's config.yaml file, specify the MongoDB Connection String in the uri field underneath mongodb:.
  7. In the FaceTec Server Webservice's config.yaml file, specify the name of the MongoDB Database in the databaseName field.
  8. Launch the FaceTec Server using Step 1 or Step 2.
  9. On success, http://<SERVER_IP_ADDRESS>:8080/status will show a JSON Success Message.

Running the FaceTec Server with PostgreSQL

PostgreSQL is another Database Type that is highly recommended and completely supported. To learn how to use PostgreSQL, see Database - Useful Queries, Metrics, & Benchmarks.

  1. Set up PostgreSQL.
  2. In Download the FaceTec SDKs, choose FaceTec Server .
  3. Click “Download the SDK”.
  4. In the Database, choose “PostgreDB”.
  5. Download and Extract the FaceTec Server.
  6. In the FaceTec Server Webservice's config.yaml file, specify the JDBC Connection String in the url field underneath postgresql:.
    • The specific Database you are connecting to should be included in the JDBC Connection String. Ex: jdbc:postgresql://<YOUR_PG_ADDRESS.<YOUR_COMPANY>.com:5432/<YOUR_DATABASE_NAME>
  7. In the FaceTec Server Webservice's config.yaml file, specify the name of the PostgreSQL User in the user field.
  8. In the FaceTec Server Webservice's config.yaml file, specify the password of the PostgreSQL User in the password field.
  9. Launch the FaceTec Server using Step 1 or Step 2.
  10. On success, http://<SERVER_IP_ADDRESS>:8080/status will show a JSON Success Message.

Running the FaceTec Server with Another Database

The FaceTec SDKs support a wide array of databases. To integrate these databases into Your System Architecture, you will need to use the FaceTec Server and create your own API interface for handling database transactions. You can use MongoDatabase.java to determine how to design your own API Interface.


Step 8: Review the Device & Server Architecture

In Steps 1 to 7, you have proven that you can properly run the FaceTec Server, make HTTPS calls via a Middle-Layer Web Service, and configure the FaceTec Server to use your chosen database. Step 8 involves reviewing the Device and Server Architecture documentation and ensuring your architecture is set up as described in the documentation. This step is crucial for integrating everything you have learned into Your Real Production Environment.

Congratulations! You have successfully completed the steps and started integrating the FaceTec Server into Your Production Environment. This step focuses on assuring Your System Architecture is completely configured and ready to go live. Before launching Your App and going live, please make sure you have finished the following:

  1. Examining the FaceTec Server Hardware Requirements.
  2. Removing any hardcoded Device Key Identifiers.
  3. Creating a plan for Upgrading your FaceTec Server every 90 days.
  4. Ensuring your System can handle unexpected increases in Load (see Server Load/Stress Testing).
  5. Creating a Blue/Green Deployment Swapping Strategy (1) (2) for zero-downtime upgrades.