FaceTec Server - Debugging Initialization (New Integrations and Upgrades)

Learn how to diagnose undesirable behaviors concerning new integrations and updates with the FaceTec Server.

New Integrations

If you are integrating the FaceTec Server for the first time, please see the Setting up the FaceTec Server Guide.

From configurations on local machines to Cloud Hosting Services, these guides have comprehensive step-by-step procedures and videos to assist Customers & Partners in running the FaceTec Server.


Updating the FaceTec Server

99% of Server Initialization problems occur when Customers do not perform according to these instructions. When updating, ensure the latest FaceTec Server version works with ZERO code modifications, THEN apply and test your own custom configurations to confirm that they still function as intended.

Zero Downtime Updates: FaceTec recommends that Customers adopt a Blue/Green Deployment Swapping Strategy (1) (2) for Zero-Downtime Updates and maintain a backup of the previous FaceTec Server until the update to the latest version is complete.

Step 1: Run the FaceTec Server Locally

Step-by-Step Guide

  1. In Download SDKs, choose the FaceTec Server.
  2. Click “Yes, take me to the Wizard!”.
  3. In Database, choose “In Memory Stubdb”.
  4. Click “Create & Download the FaceTec Server”.
  5. Download and Extract the FaceTec Server.
  6. Go to the root of the SDK directory.
  7. Run docker compose build.
  8. Run docker compose up.
  9. On success, http://localhost:8080/status will show a JSON success message.
    Additionally, the terminal running docker will output "FaceTec Server is started and ready to go."
 
Important: You must first verify that when using the Configuration Wizard that the FaceTec Server starts without ANY modifications to the code.

Diagnosing Problems Running the FaceTec Server Locally

Failing to run the FaceTec Server per Step 1 indicates potential configuration problems with the Local Environment where the FaceTec Server is being deployed. When testing in a Local Environment, ensure the configuration is exactly the same as your server.

For Usage Log Storage, please ensure Usage Logs are not being stored on Ephemeral Storage. Usage Logs must be written to a Persisted (Non-Ephemeral) File System so FaceTec can upload any pending log data after an application restart. By default, the FaceTec Server uses Docker Volumes to ensure Usage Logs are being saved to the Persistent Storage. If these Docker Settings are overwritten or need to be changed, see Usage Log Server - Storage Directory Configuration for additional guidance.

For Usage Log Server Connectivity Behaviors, ensure your Server's Ports and Proxy Settings are configured correctly, as these both can prevent your Server from properly communicating with the Usage Log Server. To learn more about the proper network settings and troubleshooting options for the Usage Log Server, see Diagnosing Usage Log Server.

To learn more about Usage Logs and the Usage Log Server, please see the Usage Logs Guide.

Step 2: Run the FaceTec Server on Remote Linux

Step-by-Step Guide

  1. Repeat steps 1 to 4 from Step 1: Run the FaceTec Server Locally.
  2. Download the FaceTec Server and rename the zip to ServerSDK.zip.
  3. Copy the FaceTec Server to your Remote Machine:
    scp -i <SSH_KEY> <PATH>/ServerSDK.zip <USER>@<REMOTE_IP>:/home/<USER>.
  4. ssh into your Remote Machine: ssh -i <SSH_KEY> <USER>@<REMOTE_IP>.
  5. Install docker (via command line).
  6. Run unzip ServerSDK.zip -d ServerSDK.
  7. Go to the FaceTec Server directory: cd ServerSDK.

  8. Run docker compose build.

  9. Run docker compose up.

  10. On success, <REMOTE_IP>:8080/status will show a JSON success message.
    Additionally, the terminal running docker will output "FaceTec Server is started and ready to go."

Diagnosing Problems Running the FaceTec Server Remotely

If the FaceTec Server fails to run in Step 2, then there is likely a misconfiguration with your Remote Environment. In addition to confirming that your Configuration is the same as your Server, please verify that your Server's Ports and Proxy Settings are configured correctly. Usage Log Storage and Usage Log Server Connectivity Behavior should be handled in the same manner as in Diagnosing Problems Running the FaceTec Server Locally.

Step 3: Successful Initialization both Locally and Remotely

Success! In the above steps, you have confirmed that you can successfully run the FaceTec Server in your local development environment, as well as on a remote server. By performing these steps, you have also verified that the FaceTec Server is running with your latest SDK Encryption Keys and that the Usage Log Server can connect to the FaceTec Servers.

If you have reached Step 3, you have successfully confirmed you can run the latest version of the FaceTec Server without any code modifications and that your Server Environment is configured correctly. By completing the previous steps, you have confirmed that any future behaviors in the Update Process result from integrating code customizations into the latest version of the FaceTec Server.

Step 4: Verifying Your SDK Encryption Keys

Important Note: By completing the first three steps in this guide successfully, you have already verified that your SDK Encryption Keys are being used correctly by the FaceTec Server.

When downloading the FaceTec Server, the SDK Encryption Keys for deviceKeyIdentifier, serverKey, and productionKeyText will be automatically configured in the FaceTec Server config.yaml file.

 

Step 5: Integrating Code Customizations

At this point, the only step remaining is to import your code customizations into the latest version of the FaceTec Server.

Important Note: FaceTec advises Customers & Partners not just copy and replace files, as any file in the FaceTec Server can receive essential updates and changes, including the config. yaml and docker-config.yaml files, inadvertently replacing these files can overwrite important code leading to undefined references and missing features causing this behavior in your environment.

FaceTec recommends working with two distinct copies of the FaceTec Server, the one with your code changes and the latest and unmodified FaceTec Server version, then tracking all customizations in all the respective files from the previous FaceTec Server, comparing each modification using a file comparison tool and applying code changes on a line-by-line basis to avert undesirable behaviors during this process.

Customers & Partners are responsible for assessing their customizations and importing the related code changes to their new instances of the FaceTec Server during updates.


Resolving Specific Server Initialization Behaviors

To diagnose and resolve specific server initialization problems, see Resolving Specific Server Initialization Behaviors.