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.gitignoreda raiz (vejamodules.md). Certifique-se de que todos os módulos necessários estão presentes emmodules/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:
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)¶
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.