Server Installation Guide

How to install the FaceTec Standard/Custom Server & Dashboard.

Quick Start

The basic steps to getting started are:

  1. Create or use an already existing MongoDB instance.
  2. Configure and start the FaceTec Dashboard.
  3. Configure and start the FaceTec Standard Server.

Definitions

FaceTec Standard Server (v9): A ZIP file containing Docker files, other config files, and a JAR file. The JAR file is a closed-source Java App that includes the FaceTec Server Core and a Web Service. The Web Service is maintained by FaceTec and interfaces via internal, prescriptive behavior to supported databases in order to record User Sessions and metadata.

FaceTec Dashboard: A ZIP file containing Docker files, other config files, and compiled Web Application. The Web Application is closed-source and built with Typescript, Angular, and Node. A Dashboard Demo is available in your Developer Account. The FaceTec Dashboard ZIP allows you to deploy this functionality into your own secure, private infrastructure.

Important Note:  Please ensure that all deployed Dashboard SDKs are not open to the public internet, utilize Basic Authentication, and have SSL configured.

MongoDB (Mongo): “The database for modern applications. MongoDB is a general purpose, document-based, distributed database built for modern application developers and for the cloud era. No database makes you more productive.”

Docker: “Debug your app, not your environment. Securely build and share any application, anywhere.”

Requirements

  1. FaceTec Standard Server (v9) is a Linux JAR and must run on a Linux Host or in a Linux Container.
  2. FaceTec Dashboard is a Node App and runs anywhere Node runs.
  3. FaceTec Standard Server (v9) and the FaceTec Dashboard must connect to a database. If the database is remote, the FaceTec Standard Server (v9) and the FaceTec Dashboard processes must have network access to the database.
  4. A database must be used. The FaceTec Standard Server (v9) supports MongoDB and S3 out-of-the-box. For other database types, the FaceTec Custom Server (v9) needs to be used.

Architecture Overview

FaceTec Server and FaceTec Dashboard can be easily hosted locally on your development machine, as well as deployed into your servers.

The following diagram shows the high level architecture of Facetec Standard Server (v9), FaceTec Dashboard, and where they fit in with your architecture and client-side Apps.

Configuration

There is a config.yaml file in the root of the FaceTec Standard Server (v9) and FaceTec Dashboard projects.

Notes:

  1. When configuring a custom port, you must make sure that the EXPOSE command in the Dockerfile is configured to the same port.

Data Storage

FaceTec Standard Server (v9) and FaceTec Dashboard store and operate on various pieces of data. This data includes:

  1. 3D FaceMaps
  2. 2D Images
  3. Session Metadata like Date, IP Address, Device Model, FaceTec Server Version, and User Agent
  4. Result information like Liveness Results and Match Results

Security

FaceTec Standard Server (v9) and FaceTec Dashboard create HTTP endpoints that access User Data and PII. You are responsible for securing this data.

Recommendations:

  1. DO Enable SSL so that data in transit is encrypted.
    • Even though your communications with the FaceTec Dashboard and the FaceTec Standard Server (v9) might be guaranteed to be on your own internal network or private cloud, it is still good practice to encrypt all data in transit!
  2. DO NOT expose your FaceTec Dashboard URLs to the public internet. If you would like to further password protect your FaceTec Dashboard deployment, please check out the following information:
  3. DO NOT open the FaceTec Standard Server (v9) and the FaceTec Dashboard ports to the Internet.

Updates & Changes


Updating

If you have an environment that experiences consistent load, we recommend Blue/Green Deployment swapping (1) (2) as an effective strategy for zero-downtime upgrades, it’s what we use here at FaceTec.

We make our best effort to make upgrading easy. You will often notice that upgrading is as simple as downloading the latest ZIPs, ensuring the same configuration, and deploying/replacing your current deployment. If there are additional steps needed to perform an update, a guide will be provided with the update.

Version 8 to Version 9 contains a schema change. FaceTec will provide an update script and full migration instructions.


Breaking Changes

Just like Web, iOS, Android, Linux, and important tools evolve, FaceTec strives to continuously improve its products and services. FaceTec must balance such improvements while maintaining stability, great developer experience, and making updates easy. Keeping the FaceTec Servers Up-to-Date gives you the ability to take advantage of the latest features, performance improvements, and bug fixes.

Below are examples of changes FaceTec makes that are “breaking”:

  • Changes to APIs
  • Changes to the configuration process
  • Changes to the way the Dashboard operates, changes to wording on pages, etc.
  • Changes to database schemas (in general, should happen infrequently)

FaceTec makes a best effort to mitigate the negative impact of these types of changes by:

  • Noting changes in the Release Notes
  • Deprecating APIs or properties before removing them
  • Providing scripts to assist with schema updates
  • Providing version-specific update guides

MongoDB Setup


Introduction

This guide explains the requirements and recommendations for hosting your own MongoDB environment and connecting it to FaceTec Server and FaceTec Dashboard.


Overview

This guide will link directly to the information you will need to get started hosting your MongoDB instances with AWS EC2, Mongo Cloud Atlas, and Amazon DocumentDB. It includes the specific steps required to connect these services with FaceTec Standard Server (v9) and FaceTec Dashboard.

Below are FaceTec’s general machine and storage requirements for your MongoDB instance, broken down by expected usage. Use these as guidance to determine the best machine for your selected hosting service.

By the end of this tutorial you will be able to produce a MongoDB URI that you will use to connect FaceTec Standard Server and FaceTec Dashboard to your MongoDB instance.


Instance Hardware Specifications

  • AWS EC2 Example Spec
    • r5.xlarge - 32GB RAM - 150 GB General Purpose SSD
  • Storage requirements
    • Data is stored in the “interactions” collection. Each record contains information about the session, an AuditTrailImage, and FaceMap.
    • Each record in the interactions collection is ~500kb.


MongoDB Cloud Hosting Pricing

 

MongoDB Cloud Atlas

  1. Get started: https://docs.atlas.mongodb.com/getting-started/.
    1. Create an Atlas Account.
    2. Deploy a Free Tier Cluster.
    3. Whitelist Your Connection IP Address.
    4. Create a Database User for Your Cluster.
    5. Connect to Your Cluster.
  2. Connect to FaceTec Server and FaceTec Dashboard.
    1. Create your connection string: https://docs.mongodb.com/manual/reference/connection-string/.
    2. Insert your MongoDB URI into your FaceTec Standard Server (v9) and FaceTec Dashboard parameterized deployments.


Setting up MongoDB on AWS EC2

  1. Create your AWS EC2 Instance.
    1. Follow the official AWS EC2 Getting Started Guide.
    2. Go to EC2 and press “Launch Instance”.
    3. Select Amazon Machine Image (AMI).
      1. In this guide, we will use the Ubuntu Server 18.04 LTS.
    4. Select your Instance Type.
    5. Add storage.
    6. Use a pre-existing or create a new security group and be sure to add a rule for incoming connections to MongoDB.
      1. MongoDB default port is 27017.
    7. Connect to your machine using the credential file you selected when starting up the instance.
  2. Set up MongoDB on you EC2 Instance.
    1. Install MongoDB on your newly provisioned AWS EC2 instance.
    2. Enable Access control and setup user accounts.
    3. Allow outside connections with IP Binding.
  3. Connect to FaceTec Standard Server (v9) and FaceTec Dashboard.
    1. Create your connection string: https://docs.mongodb.com/manual/reference/connection-string/
    2. Insert your MongoDB URI into your FaceTec Standard Server (v9) and FaceTec Dashboard parameterized deployments.

     

    AWS DocumentDB

    1. Get started: https://docs.aws.amazon.com/documentdb/latest/developerguide/getting-started.html.
      1. Create an Amazon DocumentDB Cluster.
      2. Launch an Amazon EC2 Instance.
      3. Access and Use Your Cluster using the mongo Shell.
    2. Connect to FaceTec Standard Server (v9) and FaceTec Dashboard.
      1. Create your connection string: https://docs.mongodb.com/manual/reference/connection-string/.
      2. Insert your MongoDB URI into your FaceTec Standard Server (v) and FaceTec Dashboard parameterized deployments.

    Standard Server Dashboard Deployment Guide - v9

     

    Introduction

    This guide provides an overview of the FaceTec Dashboard SDK deployment process and related information on various topics around configuration, run steps and system requirements.


    Overview

    This guide steps through the initial development steps to get the FaceTec Dashboard running locally on your dev machine and in your cloud.

    The FaceTec Dashboard is a NodeJS App and can be run using just NodeJS. FaceTec provides the FaceTec Dashboard with a Dockerfile and additional configuration files for your convenience.


    Getting Started

      You will need to configure your FaceTec Dashboard config.yaml variables. To configure this:

      • Open a file called "config.yaml" in your favorite IDE located in the root of your ZIP.
      • Modify the environment variables in this file to configure your application.

      How To Run (Locally)

      After you have set up your FaceTec Dashboard environment and have NodeJS installed on your system, you can choose from the run options below to deploy and host FaceTec Dashboard locally.

      Option 1 - Using Docker

      The below commands will build your docker image and FaceTec Dashboard Web App Container.

      $ docker-compose build

      $ docker-compose up

      Option 2 - Using Node.js

      FaceTec does not recommend you use this option in a production environment. However if you may choose to use this method for development purposes, it is the simplest option requiring no extra third-party dependencies like the above two options.

      Install Node:

      • To check your version, run node -v in a terminal window.
      • To get Node.js, go to nodejs.org.

      $ node --no-deprecation ./server/bundle.js

      Option 3 - Using PM2

      The npm package pm2 offers a variety of configuration options and is the FaceTec recommended package to use, especially deploying in a production environment.

      $ pm2 start ./server/bundle.js

       

      Connecting to MongoDB using TLS

      Copy the MongoDB security certificate to the root folder.

      Update the database connection string in the config and add tlsCAFile and retryWrites.

      mongodb: uri: "mongodb://username:password@dev-amazon:27017/?tls=true&tlsCAFile=rds-combined-ca-bundle.pem&retryWrites=false"

       

      Testing

      To check if your FaceTec Dashboard is running, you can visit localhost:3002 (or your configured URL) to see if the Dashboard and UI is correctly loaded. If you have deployed to AWS EC2 instance or custom server, visit the IP address of the server at port 3002. If you configured a custom port and a custom base url, please use the URL you configured.

      Populating Dashboard Fields

      FaceTec Dashboard REQUIRES that data is assembled into your Database in a specific way in order to function properly.

      Missing fields, or explicitly removing fields is NOT supported and may cause your Dashboard to break.

      Here's how to populate IP, Version, Device Model, App ID or Domain, Installation ID, Language, and OS/Browser.

      This data is populated by setting specific HTTP Headers to specific values.


      To Populate IP Address

      Set the “X-Forwarded-For” or "X-FT-IPAddress" HTTP Header to the IP Address of the originating call.


      Version, Device Model, etc.

      Set the “X-User-Agent” HTTP Header to the output of the FaceTec Device SDK’s createFaceTecAPIUserAgentString function.

      The Sample Apps on each platform show an example of how to get this string and send in the Headers. However, you will be calling FaceTec Standard Server from your server-side code, so make sure to get this String from the Device SDK and send to Standard Server when calling it from your server-side code.


      Browser Information

      Set the “User-Agent” HTTP Header to the User Agent header you received from the client.

      For 3D to 2D Matching, 2D Matching, 2D AgeCheck, 2D AgeEstimation, and 2D Liveness HTTP Headers are not read or used because the originating process is not a User Session.

      Please Note: FaceTec is actively working on additional mechanisms for specifying some of these additional metadata items and will be improving this in future versions.

      Deployment Steps to an AWS EC2 Instance

      1. Create an Amazon DocumentDB Cluster.
      2. Launch an EC2 instance.
        1. In this guide, we will use the Amazon Linux AMI.
      3. SSH into your instance.
      4. Install NodeJS. The below commands will install Node Version Manager and the latest version of NodeJS for Amazon Linux AMI, these steps may differ if you choose to use a different operating system.
        1. $ curl -o- https://raw.githubusercontent.com/creationix/nvm/v0.33.11/install.sh | bash
        2. $ . ~/.nvm/nvm.sh
        3. $ nvm install node
      5. Copy FaceTec Dashboard on your EC2 instance and install dependencies. There are three common ways to do this:
        • Use scp (secure copy) to copy your files to the EC2 instance.
        • Clone repo using Github, BitBucket or Gitlab.
        • Amazon S3.
      6. Start the Node.js app server and run "forever". FaceTec recommends you do this by installing and leveraging an npm package called pm2. This package essentially allows you to keep your NodeJS applications alive forever, reloading them with zero downtime when you have updates/errors to your application or server.

      Deployment Steps to AWS EB

      1. Go into your project folder, select all, and compress the files into a single .zip.
      2. The root of your ZIP should look like this:
        • Please note: It is a common mistake to ZIP the containing folder and attempt to submit this to EB. This will not work because EB requires the project files to be in a specific place.
      3. Create an EB Web Server Environment. Select Docker for the Platform and upload the Zip.
      4. Under Capacity, select t2.small instance and select Load balanced for Environment type.

      Logs & Errors

      Now you have deployed your application to either your dev machine or your cloud. Here are some common ways you may view logs and errors.


      1. Using PM2

      $ pm2 logs [instance id]


      2. Using Docker

      docker logs [OPTIONS] CONTAINER

      The above command, by default will watch and output logs from your FaceTec Dashboard Application. You can use the below command to find your Container ID of interest.

      $ docker ps


      3. Using AWS EC2

      If using AWS EC2, you can choose to enable Cloudwatch to monitor your application. Below are some baseline steps on how to configure your EC2 Instance.

      1. Create IAM Policy.
      2. Install Cloudwatch agent into EC2 instance and install awslogs agent.
      3. Configure Cloudwatch agent configuration file to choose which application you want to stream to Cloudwatch Dashboard.
      4. Start the awslogs agent.

      Hardware & Software Requirements

      • 4 or more CPUs/cores
      • At least number of CPUs * 2.5 GB of memory/RAM (e.g. a 8 CPU system needs 20 GB of RAM)
      • At least 25 GB of disk space

      FaceTec Dashboard is a Node App and will require a system with hardware and software that can support Node. Please see https://nodejs.org for more information.

      If you are using Docker, please note that the FaceTec Standard Server is a Linux Container. In development, the FaceTec Standard Server Linux Container runs on Mac, Linux, or Windows 10 Pro/Enterprise.

      In production, FaceTec recommends running FaceTec Standard Server 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 running in development.

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


      Connecting to a MongoDB Instance Running on the Host Machine when running Server Dashboard in a Container

      From the perspective of a running Container, “localhost” is the Container VM, not the Host Machine. Thus, if you have MongoDB running on the Host Machine, you will need to route the Container’s localhost through to the Host Machine. In Docker, you do this differently depending on if you are doing Mac/Windows development, or deploying this to Linux:

      • Mac & Windows
        • Update your MongoDB URI by replacing “localhost” with “host.docker.internal” which resolves to the internal IP address used by the host.
        • Example:
          • “mongodb://localhost:27017” -> “mongodb://host.docker.internal:27017”
      • Linux


      Branding Logo Customization

      1. Overwrite “branding_header_logo.png” with any image.

      Note: Do not attempt to customize other images in this folder as they will be removed in an upcoming release.

      Standard Server Deployment Guide


      Introduction

      This guide provides an overview of the FaceTec Standard Server (v9) deployment process and related information on various topics around configuration, run steps and system requirements.


      Getting Started/Requirements

      Before running the FaceTec Standard Server (v9), you should ensure you have the necessary dependencies installed. The FaceTec Standard Server (v9) is Dockerized, and FaceTec recommends that you utilize Docker to set up and run your application. However if you choose not to use Docker, you will have to manually install the below (for this guide we will use Debian):

      • Java SE Development Kit and libgomp. You can visit here to download Java or run the below command in the root of your ZIP.
        NOTE: The below command is specific for Debian used in this guide.
        • $ apt-get -y install -y default-jdk
        • $ apt-get install -y libgomp1

      If using a load balancer, you may need to increase the body size that the load balancer may accept to 10MB. AWS ElasticBeanstalk users, we have included a ‘.ebextenstions’ folder that will automatically configure your nginx load balancer to accept the body size.


      Configuration

      FaceTec Standard Server (v9) is configured through a config.yaml file located in the root directory.


      How To Run Locally Using Docker

      In a few simple steps, you can use Docker to easily run the FaceTec Standard Server (v9) on your local machine. If you have Docker and Docker Compose installed on your system, you can run the below commands in the root of your ZIP.

      $ docker-compose build

      $ docker-compose up


      Connecting to a MongoDB Instance Running on the Host Machine when running Standard Server in a Container

      From the perspective of a running Container, “localhost” is the Container VM, not the Host Machine. Thus, if you have MongoDB running on the Host Machine, you will need to route the Container’s localhost through to the Host Machine. In Docker, you do this differently depending on if you are doing Mac/Windows development, or deploying this to Linux:

      • Mac & Windows
        • Update your MongoDB URI by replacing “localhost” with “host.docker.internal” which resolves to the internal IP address used by the host.
        • Example:
          • “mongodb://localhost:27017” -> “mongodb://host.docker.internal:27017”
      • Linux


      How To Run Without Docker

      First, you should ensure that you have Java and libgomp dependencies installed on your system as noted in the “Getting Started” section above.

      Then simply run the "FaceTec-Standard-Server-<VERSION>.jar" file in the root of your ZIP.

      $ java -jar FaceTec-Standard-Server-<VERSION>.jar


      Testing

      After running the above commands, your terminal window should indicate that it is listening on port 8080 (or the port you configured). To test that your FaceTec Standard Server package is successfully running, proceed to the url below to check its status.

      http://localhost:8080/status

      You may also notice that in your terminal window an output prefixed with ZOS_c4a3j1v5dxlwpwmy1u is logged every minute. This is a heartbeat used for usage logs and indicates also that the status of your FaceTec Standard Server package is successfully running.


      Deployment Steps to an AWS EC2 Instance

      Note: A minimum AWS instance model c5.2xlarge is required to run.

      1. Create an Amazon DocumentDB Cluster.
      2. Launch an EC2 instance.
      3. SSH into your instance.
      4. Copy FaceTec Standard Server on your EC2 instance.
      5. Run the FaceTec Standard Server.
      • Using Docker:
      1. First make sure you have Docker installed and started a Docker service on your instance.
      2. Install docker-compose.
      3. Execute run steps outlined above in section "How To Run (Locally)" .
      • Without Docker:
      1. Ensure that Java and libgomp is installed on your instance.
      2. Execute the command to run the jar file outlined above in section "How To Run (Locally)" .


      Deployment Steps to AWS EB

      1. Go into your project folder, select all, and compress the files into a single .zip.
      2. The root of your ZIP should look like this:
        • Please note: It is a common mistake to ZIP the containing folder and attempt to submit this to EB. This will not work because EB requires the project files to be in a specific place.
      3. Create an EB Web Server Environment. Select Docker for the Platform and upload the Zip.
      4. Under Capacity, select c5.2xlarge instance and select Load balanced for Environment type.


      FaceTec Managed Server Limitations.

      • Inside the Standard Server and Server Dashboard ZIPs, only configuration files modification is supported. You may not modify JAR or JS files. The contents/structure of the packages may change in upcoming versions, but the method of configuration will remain constant and can be relied upon.


      FaceTec Usage Dashboard Overview

      See video walkthrough here.


      Data Management, Deletion, Privacy, GDPR, etc.

      The FaceTec Server runs completely inside of your servers and infrastructure. You have 100% control over the data that is retained.

      In order to “fully delete” data for a specific User for any reason:

      1. Delete the 3D FaceMaps and Audit Images associated with that User.
      2. Delete any other data from any databases/backups you have created that track metadata or any other information about the User.
      3. Call FaceTec Search-specific delete function(s) for that User.
        • Note: Only applicable if using FaceTec Search features.


      FAQ

      Can I call the FaceTec Standard Server directly from the device?

      This is technically possible, but not recommended. You should upload FaceTec data using your already-existing web service and call FaceTec Standard Server via secure server-to-server calls. This way, FaceTec Standard Server and its endpoints are not open to the outside world.

      Why does the Device Sample App code evaluate the response on the device?

      The Sample App code is meant to demonstrate how to parse the out-of-box FaceTec Server responses. In Production, you should make these decisions in your own web service code and decide how you want to communicate back to your own application using protocols and methodologies that you use for other non-FaceTec API calls your app already makes.

      Appendix 2: Setting up SSL

      Encrypted data transfer is an important security best practice. Calls to FaceTec Standard Server should be performed with SSL Enabled despite the call already being a secure server-to-server call inside your network.

      There are numerous ways to do this depending on your architecture and whether you are using a Cloud Provider or not. On AWS, you can use a Classic Load Balancer and connect it to Amazon Certificate Manager. There are a few additional configuration steps that you can find by searching Amazon’s documentation. If you are using another Cloud Provider, please use similar steps. If you are using your own custom servers, we recommend sending your request to a load balancer, and the load balancer will balance your load.

      The following are steps to install SSL on your FaceTec Standard Server instances if you are using AWS and Elastic Beanstalk:

      1. Pre-Conditions - Your Domain must be hosted on Route 53.
      2. Steps:
        1. Open Amazon Certificate Manager.
          1. Request a certificate.
          2. Choose Public certificate > Type in domain name > Use DNS Validation.
          3. Complete the wizard.
          4. Validation can take up to 15 minutes to issue.
        2. Open Elastic Beanstalk after the certificate has been issued.
          1. Click on Your Application > Configuration > Load Balancer.
          2. Add Listener > Listener port 443, Listener protocol HTTPS, Instance port 80, Instance protocol HTTP. For SSL Certificate, use the one you created.
          3. Save and Apply.
        3. Open Route 53.
          1. Go into Hosted Zones > Choose domain name > Create Record Set.
          2. For Name, enter your subdomain name you want to create.
          3. For Type - A IPv4 address.
          4. For Alias - Yes.
          5. For Alias Target - Your load balancer ID.
            • You can get the name of your load balancer in EC2 > Load Balancer.
          6. Click Create. Note that it may take up to 15 min for the DNS to propagate.

      See Amazon’s official documentation here.