> 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/backend1n/installation/installation_instructions.md).

# Service installation and deployment

## 1. Installation and deployment

The service is containerized, and a Docker image is available in a Facephi repository.

```bash
docker login facephicorp.jfrog.io
user: username
pass: token
```

```bash
docker pull facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
```

Where `#VERSION#` is the tag for the specific version we want to download. The tag has the prefix `v` (for example, `v5.0.0`).

## 2. Databases.

Before starting the service, the administrator must create and configure the required databases, as well as a dedicated user for the service. This **username/password must be specified in the connection string**. The database technology used by the service is determined at startup, based on the prefix of this connection string.

## 2.1 MongoDB

The environment variable `DATABASE_CONNECT_STRING` must be set to point to MongoDB.

```bash
# Accepted MongoDB prefixes.
# mongodb://
# mongodb+srv://
export DATABASE_CONNECT_STRING=mongodb://user:pass@localhost:32902/?directConnection=true&serverSelectionTimeoutMS=5000
```

The service itself will create a database named `db-backend`, if it does not already exist. It will store three collections in it:

* `media` to store images.
* `patterns` to store biometric patterns.
* `collections` for collections created using `POST /collections` (starting with version 5.0.0). If it is empty at startup, the service populates it using the `collectionId` values in `patterns` (see the version 5.0.0 release notes).

The connection string user needs read and write permissions on these three collections.

## 2.2 PostgreSQL

Likewise, the environment variable `DATABASE_CONNECT_STRING` must be set to point to PostgreSQL.

```bash
# Accepted PostgreSQL prefixes.
# postgres://
# postgresql://
export DATABASE_CONNECT_STRING=postgresql://user:pass@localhost:32903/db_backend
```

PostgreSQL differs slightly from MongoDB. A database named `db_backend` must be created beforehand by the system administrator. PostgreSQL makes it difficult to create databases from the client itself. An example of the commands the administrator should run beforehand is:

```bash
sudo -u postgres psql -c "CREATE ROLE backend1n WITH LOGIN PASSWORD 'backend1n';"
sudo -u postgres psql -c "CREATE DATABASE db_backend OWNER backend1n;"
sudo -u postgres psql -d db_backend -c "GRANT ALL ON SCHEMA public TO backend1n;"
```

Within the PostgreSQL database, the service will create three tables, as it does with MongoDB:

* `media` to store images.
* `patterns` to store biometric patterns.
* `collections` for collections created using `POST /collections` (starting with version 5.0.0), following the same automatic migration rule.

The connection string user needs permission to create tables and to read from and write to them.

## 3. docker-compose

One way to deploy the service is to create a file named `docker-compose.yml` with the following content, changing the variable values as needed. The example includes a MongoDB database; if you use an external database, remove the `mongo` service and point `DATABASE_CONNECT_STRING` to it (remember that inside the container `127.0.0.1` it is the container itself, not the host machine).

```yaml
services:
  backend1n-service:
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
    environment:
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
```

First, you must create a user directory with read and write permissions, for example `~/backend1n/config`, and place these two files in it:

* The SelphID license file `license.lic` (required). It is an online license: the machine needs outbound access to the license servers listed in section 4.4. Without a valid license, the service will not start: it logs the reason and exits with code 1.
* The service configuration file `config.json` (optional).

You must also provide the environment variable `DATABASE_CONNECT_STRING` with the database connection string (for example, `mongodb://mongo:27017`). If it is not defined, the service will not start. For debugging purposes, you can disable database operations by providing the value `no-db`. Example: `DATABASE_CONNECT_STRING=no-db`

Run the following command from the folder containing the file `docker-compose.yml`to deploy the service:

```
docker compose up
```

## 4. Additional configuration

Following the steps in **section 2**, the service is ready to start. If you need to create additional volumes for different types of resources, you can use the following additional configurations.

### 4.1 License

You can mount an additional volume and define the environment variable `LICENSE_PATH`if you want to install the license outside the usual configuration directory.

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config/config.json:/service/config/config.json
      - ~/backend1n/license/license.lic:/service/license/license.lic
    environment:
      LICENSE_PATH: /service/license
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

> `LICENSE_PATH` is a folder (inside the container, `/service/license`) that contains the file `license.lic`. In this example, the host file is `~/backend1n/license/license.lic`.

### 4.2 Service configuration

You can specify another location for the file `config.json` containing the service parameters:

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
      - ~/backend1n/custom:/service/custom
    environment:
      CONFIG_FILE: /service/custom/config.json
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

> `CONFIG_FILE` is the path, inside the container, to the configuration file. Do not mount any volume over `/service` (which contains the service executable): use a different directory, such as `/service/custom`.

If no `config.json`is specified, the following defaults are used:

```json
{
    "port": 6982,                   # Service port number.
    "number_of_threads": 0,         # Number of I/O threads; 0 = number of CPU cores.
    "connection_timeout": 0,        # Connection lifetime without reads or writes.
    "keep_alive_request_number": 0, # Sets the maximum number of requests that can be served over a keep-alive connection.
                                    # Once the maximum number of requests is reached, the connection is closed.
                                    # The default value of 0 means unlimited.
    "client_max_body_size": 100,    # Maximum allowed request body size, in Mb.
                                    # The default value is 100 Mb.
    "logger_path" : "./logs",       # Sets the base path where log files are stored (see note below about the actual nested path).
    "logger_file_prefix" : "app",   # Prefix used to name each day's log directory.
    "logger_level" : "info",        # Possible values are [trace|debug|info|warning|error|critical|off].
    "logger_rotation" : "daily",    # Possible values are [hourly|daily].
    "logger_max_files" : 0,         # The default value of 0 means unlimited.
    "auth_enabled": false,          # Enables JWT authentication for protected endpoints.
    "auth_jwt_secret": "",         # Shared secret used to validate HS256 JWT signatures.
    "auth_accept_authorization_header": true, # Accepts Authorization: Bearer <jwt>.
    "auth_accept_api_key_header": true,       # Accepts the API Key header with the JWT token.
    "auth_api_key_header_name": "x-api-key", # Name of the API Key header when enabled.
    "metrics_saturation_queue_p95_ms": 250,             # p95 (1 min) queue time above which the service is considered saturated.
    "metrics_saturation_min_inflight_ratio": 1.0,       # Fraction of configured threads that must be busy to count as saturation.
    "metrics_error_rate_warning": 0.05,                 # Error rate (5 min) above which the service is reported as degraded.
    "metrics_idle_rps_threshold": 0.01,                 # Requests per second (15 min) below which the service is reported as idle.
    "metrics_quality_alert_window_seconds": 900         # Time window for considering an extraction, search, or database operation failure relevant.
}
```

> **Actual log file path:** `logger_path` is only the base path. The final file is written to `<logger_path>/<logger_file_prefix>-<AAAA-MM-DD>/logs/app_<AAAA-MM-DD>.log` (a new directory each day). With `logger_rotation` = `hourly` the file name includes the hour (UTC): `app_<AAAA-MM-DD>_<HH>.log`. For example, with the default values (`logger_path=/service/config`, `logger_file_prefix=app`), today's log is written to `/service/config/app-2026-09-22/logs/app_2026-09-22.log`, that is, inside the mounted configuration directory. If you set `logger_path=./logs` (relative to `/service`), the log is written to `./logs/app-2026-09-22/logs/app_2026-09-22.log`. Each log line is a JSON object with at least, `timestamp`, `humanized_timestamp` and `level`.

> **Parameters `metrics_*`:** are classification policy only. They do not change what the service does, only how an already-collected snapshot is summarized in the fields `state.classification` and `alerts` of `GET /metrics`. They are read once at startup, when `config.json`; `is loaded. POST /config` does not modify them.

JWT authentication is optional and disabled by default. When enabled, `GET /health`, `GET /version`, `GET /metrics` and `GET /metrics/prometheus` remain public, while all other endpoints require a valid HS256 JWT with an unexpired `exp` claim.

Authentication rules:

* The token is sent in `Authorization: Bearer <jwt>` (the scheme is case-insensitive) and/or in the API key header (`x-api-key` by default, or the name specified in `auth_api_key_header_name`; header names are case-insensitive), according to `auth_accept_authorization_header` and `auth_accept_api_key_header`. If both headers are present, `Authorization`.
* takes precedence. Tokens signed with another secret or a different algorithm (HS384, HS512, `alg: none`), without an `exp`claim, with a `exp` non-numeric `exp` expired `or with an` nbf claim in the future are rejected.
* An unauthenticated request or a request with an invalid token returns `401` the body `{"status":401,"error":"Unauthorized","message":"…","timeStamp":"…"}` and the header `WWW-Authenticate: Bearer`. Authentication is evaluated before request body validation.
* Each unauthorized attempt is counted in `unauthorized` from `GET /metrics`.

Any of these parameters can be set using environment variables with the prefix `FACEPHI_BACKEND1N_REST_` (the key name in uppercase), which take precedence over `config.json`:

```
FACEPHI_BACKEND1N_REST_PORT=6982
FACEPHI_BACKEND1N_REST_NUMBER_OF_THREADS=2
FACEPHI_BACKEND1N_REST_CONNECTION_TIMEOUT=0
FACEPHI_BACKEND1N_REST_KEEP_ALIVE_REQUEST_NUMBER=0
FACEPHI_BACKEND1N_REST_CLIENT_MAX_BODY_SIZE=100
FACEPHI_BACKEND1N_REST_LOGGER_PATH=./logs
FACEPHI_BACKEND1N_REST_LOGGER_FILE_PREFIX=app
FACEPHI_BACKEND1N_REST_LOGGER_LEVEL=info
FACEPHI_BACKEND1N_REST_LOGGER_ROTATION=daily
FACEPHI_BACKEND1N_REST_LOGGER_MAX_FILES=0
FACEPHI_BACKEND1N_REST_AUTH_ENABLED=false
FACEPHI_BACKEND1N_REST_AUTH_JWT_SECRET=shared-secret
FACEPHI_BACKEND1N_REST_AUTH_ACCEPT_AUTHORIZATION_HEADER=true
FACEPHI_BACKEND1N_REST_AUTH_ACCEPT_API_KEY_HEADER=true
FACEPHI_BACKEND1N_REST_AUTH_API_KEY_HEADER_NAME=x-api-key
FACEPHI_BACKEND1N_REST_METRICS_SATURATION_QUEUE_P95_MS=250
FACEPHI_BACKEND1N_REST_METRICS_SATURATION_MIN_INFLIGHT_RATIO=1.0
FACEPHI_BACKEND1N_REST_METRICS_ERROR_RATE_WARNING=0.05
FACEPHI_BACKEND1N_REST_METRICS_IDLE_RPS_THRESHOLD=0.01
FACEPHI_BACKEND1N_REST_METRICS_QUALITY_ALERT_WINDOW_SECONDS=900
```

Additionally, the underlying biometric SDK (SelphID) supports the environment variable `FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD` (optional). This is the similarity value, between `0` and `100`, at which the SDK considers a facial authentication successful. The default is `65`. This variable **does not filter** the results of `POST /search/*` (which return `similarity` between 0 and 1): to discard candidates below a threshold, send `options.minSimilarity` (e.g. `0.65`).

JWT authentication settings can only be set at startup:

* Set them in `config.json` or in the environment variables `FACEPHI_BACKEND1N_REST_AUTH_*` before the service starts.
* `GET /config` never returns those JWT authentication keys.
* `POST /config` rejects those keys with `400` and cannot be used to modify them at runtime.

### 4.3 Debug and usage paths

Finally, you can specify a specific volume/path with read and write permissions for the SDK debug information and SDK usage data using the environment variables `DEBUG_PATH` and `USAGE_PATH`. The SDK creates the files `selphidDebug.log`, `selphidUsage.db` and `cntrs.db`. If these are not specified, the files are written to `/service/config`:

```yaml
services:
  backend1n-service:
    ports:
      - "6982:6982"
    volumes:
      - ~/backend1n/config:/service/config
      - ~/backend1n/debug:/service/debug
      - ~/backend1n/usage:/service/usage
    environment:
      DEBUG_PATH: /service/debug
      USAGE_PATH: /service/usage
      DATABASE_CONNECT_STRING: mongodb://mongo:27017
    image: facephicorp.jfrog.io/docker-pro-fphi/facephi-backend1n-service:#VERSION#
    container_name: facephi-backend1n-service
```

### 4.4 Network configuration

To connect to our license servers, you must add the following rules to your firewall rules:

| IP           | Port | Type   |
| ------------ | ---- | ------ |
| 52.223.22.71 | 443  | TCP/IP |
| 35.71.188.31 | 443  | TCP/IP |
| 75.2.113.112 | 443  | TCP/IP |
| 99.83.149.57 | 443  | TCP/IP |

Next, add the following `DNS` to your allowlist:

```bash
https://api.cryptlex.com:443
https://api.eu.cryptlex.com:443
```
