> 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-pt-br/sdks/backend-sdk/backend1n/installation/installation_instructions.md).

# Instalação e implantação do serviço

## 1. Instalação e implantação

O serviço está conteinerizado e há uma imagem Docker em um repositório da Facephi.

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

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

Onde `#VERSION#` é a tag da versão específica que queremos baixar. A tag tem o prefixo `v` (por exemplo, `v5.0.0`).

## 2. Bancos de dados.

Antes de iniciar o serviço, o administrador deverá criar e configurar os bancos de dados pertinentes, bem como um usuário específico para o serviço. Esse **usuário/senha deverá ser informado na string de conexão**. A tecnologia de banco de dados que o serviço utilizará será definida na inicialização, de acordo com o prefixo dessa string de conexão.

## 2.1 MongoDB

Deverá ser criada a variável de ambiente `DATABASE_CONNECT_STRING` apontando para o MongoDB.

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

O próprio serviço criará um banco de dados denominado `db-backend`, caso ainda não exista. Nele, serão armazenadas três coleções:

* `media` para armazenar imagens.
* `patterns` para armazenar padrões biométricos.
* `collections` para as coleções criadas por meio de `POST /collections` (a partir da versão 5.0.0). Se estiver vazia na inicialização, o serviço a preencherá com base nos `collectionId` presentes em `patterns` (consulte as notas da versão 5.0.0).

O usuário da string de conexão precisa ter permissões de leitura e gravação nessas três coleções.

## 2.2 PostgreSQL

Da mesma forma, deve ser criada a variável de ambiente `DATABASE_CONNECT_STRING` apontando para o PostgreSQL.

```bash
# Prefixos aceitos pelo PostgreSQL.
# postgres://
# postgresql://
export DATABASE_CONNECT_STRING=postgresql://user:pass@localhost:32903/db_backend
```

O caso do PostgreSQL difere ligeiramente do MongoDB. Um banco de dados com o nome `db_backend` deve ter sido criado previamente pelo administrador do sistema. O PostgreSQL dificulta a criação de bancos de dados a partir do próprio cliente. Um exemplo dos comandos prévios que o administrador deverá executar seria:

```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;"
```

Dentro do banco de dados PostgreSQL, o serviço criará três tabelas, assim como ocorre com o MongoDB:

* `media` para armazenar imagens.
* `patterns` para armazenar padrões biométricos.
* `collections` para as coleções criadas por meio de `POST /collections` (a partir da versão 5.0.0), com a mesma regra de migração automática.

O usuário da string de conexão precisa ter permissões para criar tabelas e ler/gravar nelas.

## 3. docker-compose

Uma forma de implantar o serviço é criar um arquivo `docker-compose.yml` com o conteúdo a seguir, alterando os valores das variáveis conforme necessário. O exemplo inclui um banco de dados MongoDB; se você usar um banco de dados externo, remova o serviço `mongo` e configure `DATABASE_CONNECT_STRING` a ela (lembre-se de que dentro do contêiner `127.0.0.1` está o próprio contêiner, não a máquina host).

```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
```

Primeiro, você deve criar um diretório de usuário com permissões de leitura e gravação, por exemplo `~/backend1n/config`, e colocar estes dois arquivos:

* O arquivo de licença do SelphID `license.lic` (obrigatório). É uma licença online: a máquina precisa ter acesso de saída aos servidores de licenças indicados na seção 4.4. Sem uma licença válida, o serviço não inicia: registra o motivo no log e termina com o código de saída 1.
* O arquivo de configuração do serviço `config.json` (opcional).

Além disso, você deve fornecer a variável de ambiente `DATABASE_CONNECT_STRING` com a string de conexão ao banco de dados (por exemplo, `mongodb://mongo:27017`). Se ela não estiver definida, o serviço não inicia. Para fins de depuração, você pode desabilitar as operações de banco de dados fornecendo o valor `no-db`. Exemplo: `DATABASE_CONNECT_STRING=no-db`

Execute o seguinte comando, dentro da pasta onde está localizado o arquivo `docker-compose.yml`, para implantar o serviço:

```
docker compose up
```

## 4. Configuração adicional

Seguindo as etapas da **seção 2**, o serviço estará pronto para iniciar. Se você precisar criar volumes adicionais para os diferentes tipos de recursos, poderá seguir estas configurações adicionais.

### 4.1 Licença

Você pode montar um volume adicional e definir a variável de ambiente `LICENSE_PATH`, caso queira instalar a licença fora do diretório de configuração habitual.

```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` é uma pasta (no contêiner, `/service/license`) que contém o arquivo `license.lic`. Neste exemplo, o arquivo no host é `~/backend1n/license/license.lic`.

### 4.2 Configuração do serviço

Você pode especificar outro local para o arquivo `config.json` com os parâmetros do serviço:

```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` é o caminho, dentro do contêiner, para o arquivo de configuração. Não monte nenhum volume sobre `/service` (contém o executável do serviço): use um diretório diferente, como `/service/custom`.

Se nenhum `config.json`for especificado, estes dados serão usados por padrão:

```json
{
    "port": 6982,                   # Número da porta do serviço.
    "number_of_threads": 0,         # O número de threads de E/S; 0 = o número de núcleos da CPU.
    "connection_timeout": 0,        # O tempo de vida da conexão sem leitura nem gravação.
    "keep_alive_request_number": 0, # Define o número máximo de solicitações que podem ser atendidas por uma conexão keep-alive.
                                    # Quando o número máximo de solicitações é atingido, a conexão é encerrada.
                                    # O valor padrão 0 significa sem limite.
    "client_max_body_size": 100,    # O tamanho máximo do body permitido nas solicitações, em Mb.
                                    # O valor padrão é 100 Mb.
    "logger_path" : "./logs",       # Define o caminho base onde os arquivos de log são armazenados (veja a observação abaixo sobre o aninhamento real desse caminho).
    "logger_file_prefix" : "app",   # Prefixo usado para nomear o diretório de logs de cada dia.
    "logger_level" : "info",        # Os valores possíveis são [trace|debug|info|warning|error|critical|off].
    "logger_rotation" : "daily",    # Os valores possíveis são [hourly|daily].
    "logger_max_files" : 0,         # O valor padrão 0 significa sem limite.
    "auth_enabled": false,          # Habilita a autenticação JWT para os endpoints protegidos.
    "auth_jwt_secret": "",         # Segredo compartilhado usado para validar assinaturas JWT HS256.
    "auth_accept_authorization_header": true, # Aceita Authorization: Bearer <jwt>.
    "auth_accept_api_key_header": true,       # Aceita o cabeçalho de API Key com o token JWT.
    "auth_api_key_header_name": "x-api-key", # Nome do cabeçalho de API Key quando habilitado.
    "metrics_saturation_queue_p95_ms": 250,             # p95 (1 min) do tempo na fila a partir do qual o serviço é considerado saturado.
    "metrics_saturation_min_inflight_ratio": 1.0,       # Fração das threads configuradas que devem estar ocupadas para contar como saturação.
    "metrics_error_rate_warning": 0.05,                 # Taxa de erro (5 min) a partir da qual o serviço é reportado como degradado.
    "metrics_idle_rps_threshold": 0.01,                 # Solicitações/segundo (15 min) abaixo das quais o serviço é reportado como inativo.
    "metrics_quality_alert_window_seconds": 900         # Janela de tempo para considerar relevante uma falha de extração, busca ou operação de banco de dados.
}
```

> **Caminho real dos arquivos de log:** `logger_path` é apenas o caminho base. O arquivo final é gravado em `<logger_path>/<logger_file_prefix>-<AAAA-MM-DD>/logs/app_<AAAA-MM-DD>.log` (um novo diretório a cada dia). Com `logger_rotation` = `hourly` o nome do arquivo inclui a hora (UTC): `app_<AAAA-MM-DD>_<HH>.log`. Por exemplo, com os valores padrão (`logger_path=/service/config`, `logger_file_prefix=app`), o log de hoje é gravado em `/service/config/app-2026-09-22/logs/app_2026-09-22.log`, ou seja, dentro do diretório de configuração montado. Se você definir `logger_path=./logs` (relativo a `/service`), o log é gravado em `./logs/app-2026-09-22/logs/app_2026-09-22.log`. Cada linha do log é um objeto JSON com, no mínimo, `timestamp`, `humanized_timestamp` e `level`.

> **Parâmetros `metrics_*`:** são apenas uma política de classificação. Não alteram o que o serviço faz, apenas a forma como um snapshot já coletado é resumido nos campos `state.classification` e `alerts` de `GET /metrics`. São lidos uma única vez na inicialização, quando o `config.json`; `POST /config` não os altera.

A autenticação JWT é opcional e está desabilitada por padrão. Quando habilitada, `GET /health`, `GET /version`, `GET /metrics` e `GET /metrics/prometheus` permanecem públicos, enquanto os demais endpoints exigem um JWT HS256 válido com uma reivindicação `exp` não expirada.

Regras de autenticação:

* O token é enviado em `Authorization: Bearer <jwt>` (o esquema não diferencia maiúsculas de minúsculas) e/ou no cabeçalho de API Key (`x-api-key` por padrão, ou o nome indicado em `auth_api_key_header_name`; os nomes dos cabeçalhos não diferenciam maiúsculas de minúsculas), conforme `auth_accept_authorization_header` e `auth_accept_api_key_header`. Se ambos os cabeçalhos forem enviados, prevalece `Authorization`.
* Tokens assinados com outro segredo ou outro algoritmo (HS384, HS512, `alg: none`), sem `exp`, com `exp` não numérico, com `exp` expirado ou com `nbf` no futuro são rejeitados.
* Uma solicitação não autenticada ou com um token inválido responde `401` com o corpo `{"status":401,"error":"Unauthorized","message":"…","timeStamp":"…"}` e o cabeçalho `WWW-Authenticate: Bearer`. A autenticação é avaliada antes da validação do corpo da solicitação.
* Cada tentativa não autorizada é contabilizada em `unauthorized` de `GET /metrics`.

Qualquer um desses parâmetros pode ser definido por variáveis de ambiente com o prefixo `FACEPHI_BACKEND1N_REST_` (o nome da chave em maiúsculas), com precedência sobre o `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
```

Além disso, o SDK biométrico subjacente (SelphID) aceita a variável de ambiente `FACEPHI_SELPHID_FACIALAUTHENTICATION_THRESHOLD` (opcional). Esse é o valor de similaridade, entre `0` e `100`, a partir do qual o SDK considera positiva uma autenticação facial. O valor padrão é `65`. Essa variável **não filtra** os resultados de `POST /search/*` (que retornam `similarity` entre 0 e 1): para descartar candidatos abaixo de um limite, envie `options.minSimilarity` (por exemplo, `0.65`).

Os parâmetros de configuração da autenticação JWT só podem ser definidos na inicialização:

* Configure-os em `config.json` ou nas variáveis de ambiente `FACEPHI_BACKEND1N_REST_AUTH_*` antes de iniciar o serviço.
* `GET /config` nunca retorna essas chaves de autenticação JWT.
* `POST /config` rejeita essas chaves com `400` e não pode ser usado para modificá-las em tempo de execução.

### 4.3 Caminho de depuração e de uso

Por fim, você pode especificar um volume/caminho específico com permissões de leitura e gravação para as informações de depuração do SDK e os dados de uso do SDK, por meio das variáveis de ambiente `DEBUG_PATH` e `USAGE_PATH`. O SDK cria nesses caminhos os arquivos `selphidDebug.log`, `selphidUsage.db` e `cntrs.db`. Se não forem especificados, os arquivos serão gravados em `/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 Configuração de rede

Para se conectar aos nossos servidores de licenças, você deve adicionar as seguintes regras ao firewall:

| IP           | Porta | Tipo   |
| ------------ | ----- | ------ |
| 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 |

Em seguida, adicione os seguintes `DNS` à sua lista de permissões:

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