Ir para o conteúdo

Guia de Instalação e Execução — HDT-AF

Este documento consolida os pré-requisitos, instalação de dependências, configuração de ambiente, execução em desenvolvimento, suítes de testes e build de produção do HDT-AF. Para detalhes aprofundados sobre scripts individuais e implantação em servidor remoto, consulte execution-guide.md e vm-deployment-guide.md.


1. Pré-requisitos

Componente Requisito Uso
Java (JDK) JDK 25 (reator Maven e chaincode real) / JDK 17 (app Android) Compilação e execução do núcleo federado e Gradle
Apache Maven 3.9+ no PATH Build e testes dos 22 módulos do reator
Docker & Docker Compose Docker Engine + Compose v2 Broker Mosquitto TLS, Hyperledger Fabric, clientes em contêiner e stack de observabilidade
Android SDK / Gradle Android SDK API 35 (compilação :app / d8) Apenas para compilar o cliente Android e plugins DEX (federated-android-client)
Python 3.10+ & PlantUML mkdocs, mkdocs-material, mkdocs-mermaid2-plugin, pytest, plantuml Apenas para construir/servir o portal de documentação (modules/federated-docs)
Utilitários de SO lsof, pgrep, openssl Gerenciamento de porta 8088 e geração de certificados TLS/X.509

Nota sobre o repositório: Os diretórios dentro de modules/ são repositórios Git independentes ignorados pelo .gitignore da raiz (veja modules.md). Certifique-se de que todos os módulos necessários estão presentes em modules/ antes de executar o reator.


2. Instalação e Compilação

2.1 Núcleo Java (Reator Maven + Classpath de Execução)

# Compila e instala os 22 módulos e copia dependências externas para target/lib/
sh scripts/compile.sh

2.2 Cliente Android (Opcional)

cd modules/federated-android-client
./gradlew :core:test :app:assembleDebug :client-engine-plugin:dexRelease

2.3 Portal de Documentação (Read the Docs / MkDocs)

pip install -r modules/federated-docs/requirements.txt
sh modules/federated-docs/scripts/build-docs.sh

3. Configuração de Ambiente (.env)

Crie o arquivo .env na raiz a partir do modelo versionado:

cp .env.example .env

Principais grupos de variáveis carregados por scripts/run-admin-web.sh e pelos processos Java (System.getProperty tem precedência sobre System.getenv):

Grupo Variáveis essenciais Padrão / Observação
Ledger (Fabric) FEDERATED_LEDGER_MODE, FABRIC_GATEWAY_PEER_ENDPOINT, FABRIC_GATEWAY_TLS_CERT_PATH, FABRIC_GATEWAY_CERT_PATH, FABRIC_GATEWAY_KEY_PATH, FABRIC_CHANNEL_NAME, FABRIC_CHAINCODE_NAME, FABRIC_FAIL_ON_ERROR Apenas blockchain é suportado. Gateway usa localhost:7051, canal federated-channel, chaincode federated-governance. .env.example define FABRIC_FAIL_ON_ERROR=false para desenvolvimento; o padrão interno Java é true.
MQTT 5 & TLS/mTLS MQTT_BROKER_URL, MQTT_TLS_TRUSTSTORE, MQTT_TLS_TRUSTSTORE_PASSWORD, MQTT_TLS_KEYSTORE, MQTT_TLS_KEYSTORE_PASSWORD, MQTT_TLS_TRUSTSTORE_TYPE, MQTT_TLS_KEYSTORE_TYPE, MQTT_USERNAME, MQTT_PASSWORD docker/mosquitto/mosquitto.conf escuta em TLS 1.3 + mTLS na porta 8883 (ssl://localhost:8883). Gere material local com sh scripts/generate-mqtt-tls.sh.
Assinatura & LGPD LGPD_PSEUDONYM_SALT, SIM_HMAC_SECRET, SIGNING_CA_CERT, SIGNING_DIR, SIGNING_KEYSTORE_PASSWORD, SIGNING_PEER_IDENTITIES Em produção defina LGPD_PSEUDONYM_SALT e SIM_HMAC_SECRET fortes; identidades X.509 podem ser geradas com sh scripts/generate-signing-identities.sh.
Monitor Web & SSE ADMIN_TLS_KEYSTORE, ADMIN_TLS_PASSWORD, ADMIN_TLS_DISABLED, ADMIN_STATIC_ROOT, ADMIN_WEB_MAX_SSE_CONNECTIONS, ADMIN_ROUND_SYNC_TIMEOUT_MS Porta fixa 8088. DEFAULT_MAX_SSE_CONNECTIONS=24, timeout síncrono de rodada 15000 ms.
Runtime Paths (var/) HDT_AF_DATA_ROOT, HDT_AF_ARTIFACT_ROOT, HDT_AF_RUNTIME_STATE_ROOT, HDT_AF_DEPLOYED_EXPERIMENTS_ROOT, HDT_AF_DEPLOYED_DATASETS_ROOT, HDT_AF_DEPLOYED_CLIENT_PACKAGES_ROOT Pacotes implantados persistem sob var/ (não são apagados por mvn clean).
Arquivo MQTT (Opt-in) MQTT_ARCHIVE_MONGODB_URI, MQTT_ARCHIVE_MONGODB_DATABASE, MQTT_ARCHIVE_MONGODB_COLLECTION Desativado por padrão; se configurado, arquiva todos os envelopes (#) no MongoDB (hdt_af.mqtt_messages).
Inferência HTTP HDT_MODEL_WORK_DIR, HDT_MODEL_API_HOST, HDT_MODEL_API_PORT Padrão 127.0.0.1:8092, target/model-work.

4. Execução em Desenvolvimento

4.1 Subir Infraestrutura Local (Mosquitto TLS + Fabric)

# 1. Provisionar certificados MQTT TLS/mTLS e identidades X.509 (se ainda não gerados)
sh scripts/generate-mqtt-tls.sh
sh scripts/generate-signing-identities.sh

# 2. Subir broker Mosquitto TLS
docker compose up -d mosquitto

# 3. Empacotar chaincode Fabric (exige FABRIC_HOME configurado)
sh scripts/fabric-package-chaincode.sh

4.2 Iniciar o Monitor Web & API REST (:8088)

sh scripts/run-admin-web.sh

Acesse: - Dashboard do Monitor: http://127.0.0.1:8088/ - Swagger UI: http://127.0.0.1:8088/swagger-ui/ - Especificação OpenAPI 3.1: http://127.0.0.1:8088/openapi.yaml

4.3 Executar Experimentos e Serviços Auxiliares

# Experimento smoke autossuficiente (sem datasets externos)
sh scripts/run-smoke-experiment.sh

# Serviço HTTP de inferência de modelos (:8092)
sh scripts/run-model-inference.sh

# Simulador IoT Replay (modos: har | ecg)
sh scripts/run-iot-simulator.sh har

# Portal local de documentação (http://127.0.0.1:8000)
sh modules/federated-docs/scripts/serve-docs.sh

5. Execução de Testes

# Suíte completa (inclui validação de scripts de empacotamento + todos os módulos Maven)
sh scripts/run-tests.sh

# Apenas testes unitários e de integração rápidos (exclui @Tag("e2e"))
sh scripts/run-tests.sh --fast

# Módulo Maven específico
sh scripts/run-tests.sh --module federated-local-cdm

# Cobertura JaCoCo (módulos configurados no script)
sh scripts/run-coverage.sh --all

# Testes do portal de documentação (Python / MkDocs)
sh modules/federated-docs/scripts/build-docs.sh

6. Build e Execução em Produção (Docker / VM)

Para construir a imagem multi-módulo (docker/Dockerfile.app) e implantar em VM com dual-network bridging (hdt-net + fabric_test), siga o passo a passo em vm-deployment-guide.md e a referência de contêineres em ../docker/README.md.