FaceTec Server Getting Started

Learn the basics about the FaceTec Servers.


FaceTec Standard Server (v9) & Server Dashboard

The FaceTec Standard Server (v9)  & FaceTec Server Dashboard are recommended for Developers new to FaceTec because they provide a prescriptive, "fully managed" approach to deployment. Both packages require zero code to configure and deploy, both are closed-source, and both are controlled via a single YAML config file.

Once deployed, the FaceTec Standard Server (v9) is used via the HTTPS API. See more at API Reference Guide.

The Server Dashboard is then used to view, monitor, and analyze your results in your own secure, private environment. See the Dashboard Demo Page to check out the Usage you have when using the Test API.


FaceTec Custom Server (v9)

If you need additional customization or features not provided by the FaceTec Standard Server (v9), you will need to download, run, and customize the FaceTec Custom Server (v9) to fit your needs.

The FaceTec Custom Server (v9) wraps the FaceTec Server Code and Server Core in an application and provides a Dockerfile and additional configuration files to make initial development, testing, and deployment easy.


FaceTec Server Core

Both the FaceTec Standard and Custom (v9) Servers use the FaceTec Server Core for core functionality. The FaceTec Server Core is a Java JAR and can be integrated into any Java Application for ultimate flexibility.

Warning! Directly using the FaceTec Server Core in a custom Java Application is heavily discouraged, except for large organizations with special security/customization requirements and readily available resources to customize implementations, to keep Up-to-Date with SDK Versions, and to stay current with Security Best Practices.

Prerequisites

The FaceTec Standard & FaceTec Custom (v9) Servers run on any platform by using Docker. If you want to run locally on your Mac or PC, you will need to download and install Docker.

Docker + Windows Users: You will need to make sure your Shared Drives are configured correctly. This usually means you just need to allow access to your C drive. Please see the Docker Guides for more information.

We reference Docker frequently in this guide and in our FaceTec Server ZIP files. Docker is not required to run the FaceTec Server, but depending on what you are doing, it does make certain aspects of development and deployment easier.


Running the FaceTec Server Locally

  1. cd to the extracted directory.
  2. Run docker-compose build for Standard Server or build.sh for Custom Server.
  3. Run docker-compose up for Standard Server or run.sh for Custom Server.
  4. FaceTec Server HTTPS API will run on http://localhost:8080

Custom Server Code Changes

  1. If your server is running then stop it by running docker-compose down.
  2. Make your changes to the Custom Server code.
  3. Run build.sh followed by run.sh.
  4. Your changes will now be deployed to your local FaceTec Server.

Enabling 1:N Search

1. Add search directory to docker-compose.yml

volumes:
      - ./MyTestFaceTec3DDB:/home/MyTestFaceTec3DDB

2. Add search directory to config.yaml

searchDatabaseRootDirectory: /home/MyTestFaceTec3DDB

Running the FaceTec Server using the IntelliJ Docker Plugin

  1. Install the Docker Plugin in IntelliJ.
  2. From the FaceTec Server root directory run "compile.sh" which will install the jar into your local maven repo (Custom Server Only).
  3. Open the FaceTec Server root directory in IntelliJ.
  4. Open the DockerFile.
  5. Click Run on Docker.
  6. Once finished add port binding to localhost:8080 in IntelliJ and click save.

Testing the FaceTec Server Locally with Postman

Once the Server is running, run the Postman Test Suite against the localhost environment, which will demonstrate all functionality of the FaceTec Server with 100% working API calls, data, and tests.


Using Device SDKs With Your Local FaceTec Server

To run the Device SDKs and process the 3D FaceScans and ID Scans with your Local FaceTec Server:

  1. Update the BaseURL variable in your Config file in the Device SDK to the URL of your FaceTec Server.
  2. Run the App and do some Sessions!


Running Browser SDK against Local FaceTec Server

For the Browser Device SDK, if you are running on the same machine as the FaceTec Server, use "http://localhost:8080" to point the Browser SDK at your local FaceTec Server.


Running iOS/Android SDK against Local FaceTec Server

For iOS and Android Device SDKs, running against your Local FaceTec Server is trickier since the Device needs access to your FaceTec Server and is not simply on "localhost" like it is when running the Browser SDK. You may find it easier to fully deploy the FaceTec Server to a QA environment to test iOS and Android.

While we are unable to provide catch-all steps that point your iOS/Android Device SDK at your Local FaceTec Server, in general you just need to make sure that the BaseURL in the Config file is reachable by your Device. This could be a specific ip address and port for your machine, or local DNS/machine name. Also, because hosting on http://localhost:8080 by default is not using SSL, you will need to update the Android Sample to Allow Cleartext Traffic and iOS Sample to use a App Transport Security exception.

If your iOS/Android device is connected to the same network as the machine running your Local FaceTec Server you may be able to substitute that machine's local IP address for "localhost". For example, http://localhost:8080 becomes http://192.168.2.10:8080.


Deployment Overview


Understanding FaceTec Server Package Differences

Before reading about Deployment, it is important to understand the 3 types of FaceTec Server packages:

  1. FaceTec Standard Server - a standalone JAR that creates a HTTPS API.
  2. FaceTec Custom Server - a Java project that can be compiled that contains source code to compile the HTTPS API along with Server Core yourself.
  3. FaceTec Server Core - a JAR that can be imported into a Java program and used in advanced, custom implementations.


Docker vs. Standalone

Some important points to note about Running/Deploying with or without Docker:

  • Standard Server and Custom Server both ship with a Dockerfile and can be ran via Docker anywhere Docker runs.
  • Docker is not required for Standard Server. Standard Server can be ran without Docker as a normal Java program.
  • Docker is not required for Custom Server. Custom Server can be compiled and ran without Docker as a normal Java program.
  • Docker is not applicable for the FaceTec Server Core since it is a lib that must be included in other projects.


What Infrastructure & Tech Stack does FaceTec Recommend?

FaceTec Servers run anywhere, and thus, we recommend using it in an infrastructure you are familiar with!

Here at FaceTec, we use AWS & Elastic Beanstalk Clusters of FaceTec Servers. This allows for automatic load balancing and scaling. The FaceTec Server is a stateless (no sessions) server that is designed to be horizontally scaled (add more servers during high usage).

You are free to use whatever infrastructure you desire, including AWS, Azure, Google Cloud, or your own Custom Cloud. The FaceTec Standard and Custom (v9) Servers are designed to be interacted with over an HTTPS API, so you can call them from your own web service with ease, and using secure, server-to-server API Calls.


Security Note

In Production, please DO NOT allow the FaceTec Server to handle requests from the public internet. Your web service should handle requests from Your App, and should send requests to the FaceTec Server using secure server-to-server calls. Calling the FaceTec Server directly from Your Apps should only be done during initial integration and bootstrapping.


Integrating & Deploying to QA or Production Servers - Custom Infrastructure


Deploying to a Custom Infrastructure

While we do not know what your Custom Infrastructure is, we have these helpful tips:

  1. Linux - While the FaceTec Servers run anywhere using Docker, for Production, running on Modern Linux is recommended for performance reasons. Running via Docker on Linux is 100% supported and will not degrade performance.
  2. CPU Hardware matters. FaceTec Servers do heavy Computer Vision and Machine Learning operations and take advantage of the latest advancements in CPU technology. Intel Xeon Platinum 8000 Series or above is recommended.
  3. Clusters, Load Balancing, Monitoring, and Alerting - if you are creating your own custom infrastructure, please note that you do not get certain important and useful tools that are provided in turnkey fashion by the major Cloud Providers. Setting up Clusters of Machines, Load Balancing, and Monitoring and Alerting will need to be custom-built and tested.


Using Custom Databases

You are free to use whatever Database you would like with Custom Server. You just need to use Custom Server and write your own subclass of FaceTecDatabase.

We encourage you to send us your FaceTecDatabase subclass Java file implementations so we can ensure the behavior of your Custom Implementation in future versions!


Integrating & Deploying to QA or Production Servers - AWS Elastic Beanstalk

Overview

To deploy the FaceTec Server to EB, you must first upload the FaceTec Server JAR to S3, configure specific permissions, then use the special files and folders we have created to update the configuration to point at your S3 bucket.


Step 1: Get the V9 SDK

We highly recommend using the Configuration Wizard, as this will pre-fill the Config files with your Keys (except your private FaceMap Encryption Key) and otherwise create a pre-configured SDK ZIP for you. If you do not use the Config Wizard, you will need to download the SDK and update the config.yaml file yourself and test that your changes are correct.


Step 2: Upload the FaceTec Server JAR to S3 and configure permissions

  1. Create an S3 bucket to host the SDK JAR.
  2. Create a new Role.
  3. Create a new Policy for that Role. Give this policy GetObject permissions to the bucket you created above.


Step 3: Updating the configuration in the extracted ZIP

Please make sure to enable showing hidden files. On Mac, this is CMD+SHIFT+. and from the Terminal to list hidden files, run "ls -A". The .ebextensions folder, which is required for EB, is a hidden folder in the AWS-EB-StubDir folder in the Custom and Standard Server ZIP.

  1. Find the folder called AWS-EB-StubDir in your Standard or Custom Server ZIP. You will deploy to EB using this folder.
  2. In the .ebextensions subfolder, there is a file called 02_download_server_sdk_jar_from_s3.config that must be configured to where you are hosting the FaceTec Server JAR file.
    1. Edit this line: "aws s3 cp s3://<insert/path/to/your/FaceTecServerSDK/jar/bucket>/FaceTec-Custom-Server.jar /tmp/FaceTec-Custom-Server.jar"
    2. Update the line above to the path that is accessible by your EB cluster and where the FaceTec Server JAR is located.


Step 4: Create your EB Cluster and Deploy

  1. If this is the first time you are creating your cluster, run "eb init" and follow the instructions to start your cluster. Use Docker deployment instead of Java deployment.
  2. Now, run "eb create <INSERT_ENVIRONMENT_NAME_TO_CREATE> -i c5.2xlarge -ip <ROLE_NAME_YOU_CREATED_IN_AWS_IAM>"

If successful, your FaceTec Server cluster is now up and running! You can check out your Elastic Beanstalk Dashboard for more information, alert and load trigger, logging, etc.


Step 5: Re-deploy

To re-deploy after changes or upgrading the library, just run "eb deploy".


Step 6: Additional Configurations

  1. By default, the FaceTec Server is hosted on port 8080. In order for traffic to the load balancer to route correctly, you need to update your Network Configuration to pass through connections from port 80 to 8080.
  2. FaceTec recommends installing SSL on your EB Load Balancer. This involves getting a SSL Certificate and applying to your Load Balancer.

Docker Support

The FaceTec Server Core is a Linux Container.

During Development, Your Team can run the FaceTec Server on Linux, Windows, and macOS* -- all via Docker.

For Production, FaceTec recommends running FaceTec Linux Containers on a Linux Host. AWS, Google Cloud, and Azure support numerous methods of deployment of Linux Containers.

For Custom/Private Linux Deployments, a Basic Deployment can be configured using the same steps as those used during Development.

Although Linux Hosts are strongly recommended, if Windows Hosts are an absolute requirement, Linux Containers can be ran on Windows Server 2016, 2019, and systems that support WSL 2.

* Important Note: FaceTec Server's Core Features cannot be used on macOS. The FaceTec Server is only designed to initialize, so it can be used for testing on macOS Systems during Initial Development.

Windows (via Docker)

The FaceTec Server can be used on Windows (via Docker) for Initial Development.

The FaceTec Device SDKs can run against the FaceTec Server (via Docker) when both are hosted on the same machine. However, this type of configuration is only intended for testing. In a Real Production System, Your Team should have a Middle-Layer Webservice that operates between the FaceTec Device SDKs and FaceTec Server.


macOS (via Docker)

The FaceTec Server can be launched and initialized on a macOS System (via Docker). However, the FaceTec Server's Core Features cannot be used on a macOS System for Initial Development.

Since FaceTec Server's Core Features cannot be used on macOS, the FaceTec Device SDKs will not initialize properly when running against a FaceTec Server on a macOS System.


Final Steps - Securing Your Deployment

FaceTec SDKs are deployed into many very large organizations, banks, financial institutions, governments, and more. The vast majority of large entities have specific and highly varying security requirements, philosophies, and levels of sophistication. The FaceTec Device SDKs & FaceTec Server provide a high degree of flexibility in terms of server-side app architecture.

FaceTec requires that Customers & Partners to handle the transfer of the 3D FaceScan, Audit Trail Images, and any other FaceTec-related data using your Application's pre-existing, already-vetted, blessed-by-your-security-team's communication channels from your secure application code to your server.

Once the 3D FaceScan and other required data is into your secure server environment, you will be calling the HTTPS endpoints created by this deployment using a secure, server-to-server HTTPS call.


Popular Customizations

The Custom Server includes the HTTPS API code that can be modified to fit your needs.

Moving Variables from Config to Server Environment Variables

We recommend modifying the FaceTecInstanceManager.java file and replacing all the config. references with environment variables.