TechTrue On-Premises

O TechTrue On-Premises permite executar o serviço de reconhecimento facial em ambiente local, utilizando Docker Compose. Depois que o ambiente está instalado e o token válido foi gerado, as operações da API são feitas localmente pela URL configurada no servidor do cliente.

Por padrão, este guia considera a API disponível em http://localhost:3001.

Resumo de implantação

Item	Informação
Execução	Local, via Docker Compose
URL base padrão	http://localhost:3001
Banco de dados padrão	PostgreSQL interno gerenciado pelo Docker
Validade do token	24 horas
Internet	Necessária para autenticar no registro, baixar imagens quando ainda não estiverem em cache e gerar ou renovar o token
Arquivos fornecidos	docker-compose.yml e fiducia-client-key.json

Cuidado

O arquivo fiducia-client-key.json, a key, o secret e o token gerado são credenciais sensíveis. Mantenha esses dados restritos ao ambiente autorizado.

Pré-requisitos

Antes de iniciar a instalação, confirme que o servidor possui:

• Docker instalado e em execução.
• Docker Compose instalado.
• Acesso à internet para autenticar no registro de imagens, baixar as imagens na primeira execução e gerar ou renovar o token.
• Os arquivos enviados pela TechTrue: docker-compose.yml e fiducia-client-key.json.

Personalização do Docker Compose

O arquivo docker-compose.yml pode ser ajustado de acordo com a infraestrutura do cliente. As alterações abaixo são seguras quando feitas com cuidado.

Porta de acesso à API

No mapeamento de portas, o primeiro número representa a porta exposta no servidor do cliente. O segundo número representa a porta interna do container e deve permanecer igual ao arquivo entregue.

Exemplo para expor a API na porta 8080 do servidor:

on-premise-api:
  ports:
    - "8080:8080"

Depois da alteração, a URL base passa a ser:

http://localhost:8080

Banco de dados próprio

Por padrão, o ambiente sobe um PostgreSQL interno gerenciado pelo Docker. Se o cliente preferir usar um banco já existente na própria infraestrutura, remova o serviço postgres do docker-compose.yml e aponte o serviço face-api para o banco externo:

face-api:
  environment:
    POSTGRES_HOST: seu-servidor-db
    POSTGRES_PORT: "5432"
    POSTGRES_USER: seu-usuario
    POSTGRES_PASSWORD: sua-senha
    POSTGRES_DB: face_api

Nota

Ao usar banco próprio, crie previamente o banco com o nome face_api. As tabelas serão criadas automaticamente na primeira execução do serviço.

Credenciais do banco interno

Caso o cliente mantenha o PostgreSQL interno, o usuário e a senha padrão podem ser alterados. Mantenha sempre os mesmos valores nos serviços postgres e face-api:

postgres:
  environment:
    POSTGRES_USER: meu-usuario
    POSTGRES_PASSWORD: minha-senha

face-api:
  environment:
    POSTGRES_USER: meu-usuario
    POSTGRES_PASSWORD: minha-senha

Cuidado

Variáveis como CREDENTIAL_SECRET_KEY, GCP_SERVICE_API_URL e as imagens Docker são configuradas pela TechTrue para o ambiente contratado e não devem ser alteradas.

Instalação inicial

1. Criar a pasta do projeto

Crie uma pasta para armazenar os arquivos do serviço:

mkdir fiducia-onpremise
cd fiducia-onpremise

Copie para essa pasta os dois arquivos recebidos da TechTrue:

• docker-compose.yml
• fiducia-client-key.json

2. Autenticar no registro de imagens

Execute o login no registro de imagens Docker na máquina onde o serviço será executado:

cat fiducia-client-key.json | docker login -u _json_key \
  --password-stdin https://us-central1-docker.pkg.dev

Quando a autenticação for concluída com sucesso, o Docker exibirá:

Login Succeeded

3. Subir o ambiente

Inicie os containers:

docker compose up -d

Na primeira execução, o Docker fará o download das imagens necessárias. Aguarde até que todos os serviços estejam em execução.

4. Conferir os containers

Verifique o status dos serviços:

docker compose ps

Todos os containers do ambiente devem aparecer com status Up.

Geração de token

O token é gerado pelo serviço local e tem validade de 24 horas. Durante a geração, o sistema reporta automaticamente a contagem de faces cadastradas à TechTrue. Por isso, é necessário que o servidor tenha acesso à internet nesse momento.

curl -s -X POST http://localhost:3001/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{"key": "{{sua-key}}", "secret": "{{seu-secret}}"}'

Resposta esperada:

{
  "token": "eyJhbGci..."
}

Cuidado

Guarde o token retornado em local seguro. Ele será usado no cabeçalho Authorization das requisições e deverá ser renovado após 24 horas.

Uso da API local

Depois de gerar o token, todas as operações de face são realizadas localmente, sem necessidade de internet para as chamadas da API.

A API On-Premises segue os mesmos endpoints da API online para as operações de face. A diferença é a URL base e o endpoint usado para gerar o token.

API online	API On-Premises
URL base da documentação online	http://localhost:3001 ou a porta configurada pelo cliente
POST /api/v1/app-credentials/token	POST /api/v1/token

Consulte também:

• Autenticação
• Faces

Listar faces cadastradas

curl http://localhost:3001/api/v1/services/face/list \
  -H "Authorization: Bearer {{token}}"

Cadastrar uma face

Prepare um arquivo JSON com a imagem em Base64:

python3 -c "
import base64, json
with open('imagem.jpeg', 'rb') as f:
    b64 = base64.b64encode(f.read()).decode()
json.dump({
    'doLivenessCheck': False,
    'ReturnTemplate': False,
    'Images': [{'imageType': 'frontal', 'imageData': b64}]
}, open('/tmp/enroll.json', 'w'))
"

Envie a requisição de cadastro:

curl -X POST http://localhost:3001/api/v1/services/face/enroll/{{id-da-pessoa}} \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d @/tmp/enroll.json

Identificar uma face

Prepare um arquivo JSON com a imagem em Base64:

python3 -c "
import base64, json
with open('imagem.jpeg', 'rb') as f:
    b64 = base64.b64encode(f.read()).decode()
json.dump({
    'Images': [{'imageType': 'frontal', 'imageData': b64}]
}, open('/tmp/identify.json', 'w'))
"

Envie a requisição de identificação:

curl -X POST http://localhost:3001/api/v1/services/face/identify \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -d @/tmp/identify.json

Renovação do token

Quando o token expirar, repita o processo de geração de token. O serviço local continua disponível; apenas a geração ou renovação do token exige acesso à internet.

Checklist de validação

Antes de entregar o ambiente para uso, confirme:

• Os arquivos docker-compose.yml e fiducia-client-key.json estão na pasta do projeto.
• O login no registro Docker foi concluído com sucesso.
• Todos os containers aparecem com status Up.
• O token foi gerado pelo endpoint local POST /api/v1/token.
• As chamadas da API usam a URL base local e o cabeçalho Authorization: Bearer {{token}}.