Guia de Implantação da Stack HDT-AF em Máquina Virtual (VM)¶
Este guia documenta o procedimento completo de implantação, configuração, verificação e resolução de problemas da plataforma HDT-AF na máquina virtual remota (192.168.10.198), integrando contêineres Docker da aplicação com a rede de governança Hyperledger Fabric.
1. Visão Geral da Infraestrutura¶
A stack HDT-AF na VM opera em um modelo híbrido de contêineres Docker coordenados via Docker Compose e integrados a uma rede Hyperledger Fabric em execução no mesmo host.
| Componente | Host / IP | Especificação / Versão | Função |
|---|---|---|---|
| Host VM | 192.168.10.198 |
Debian GNU/Linux 12 (Kernel 6.8.12-43-pve x86_64) | Ambiente de execução e hospedeiro Docker |
| Admin Web & Orchestrator | Contêiner hdt-af-hdt-af-admin-1 |
hdt-af:latest (Linux/amd64, OpenJDK 25) |
Interface web, REST API, orquestrador federado e Gateway Fabric |
| Broker MQTT 5 | Contêiner hdt-af-mosquitto-1 |
eclipse-mosquitto:2 |
Barramento pub/sub com mTLS (8883), TCP plain (1883) e WS (9001) |
| Persistência Local CDM | Contêiner hdt-af-postgres-1 |
postgres:16-alpine |
Banco de dados relacional e séries temporais do CDM |
| Hyperledger Fabric | Contêineres de rede fabric_test |
Hyperledger Fabric v2.5 / Test-Network | Ledger distribuído de governança imutável (federated-channel) |
2. Topologia de Redes e Mapeamento de Portas¶
2.1 Modelo de Dupla Rede (Dual-Network Bridging)¶
Para viabilizar a comunicação com os nós do Hyperledger Fabric sem recorrer a configurações frágeis de /etc/hosts ou proxies no host, o contêiner hdt-af-admin foi configurado com multihoming (conectado a duas redes Docker bridge):
hdt-net(Bridge interna gerenciada pelo Docker Compose):- Conecta
hdt-af-admin,mosquittoepostgres. - Permite resolução de nomes interna por serviço (
mosquitto:8883,postgres:5432). fabric_test(Bridge externa gerenciada pela rede Fabric):- Conecta
hdt-af-adminaos peers e orderer do consórcio. - Permite resolução de nomes DNS direta:
peer0.org1.example.com:7051,peer0.org2.example.com:9051,orderer.example.com:7050.
2.2 Tabela de Portas Expostas no Host¶
| Porta Host | Porta Interna | Protocolo / Serviço | Descrição |
|---|---|---|---|
8088 |
8088 |
HTTP (hdt-af-admin) |
Dashboard web do monitor federado e endpoints da REST API |
8883 |
8883 |
MQTTS (mosquitto) |
Broker MQTT 5 com autenticação mTLS e cifra TLS 1.3 |
1883 |
1883 |
MQTT (mosquitto) |
Broker MQTT 5 não autenticado (testes e telemetria interna) |
9001 |
9001 |
WebSocket (mosquitto) |
Suporte a clientes via WebSocket |
15432 |
5432 |
PostgreSQL (postgres) |
Porta remapeada para evitar conflito com serviço local do host (vaideferry-db) |
[!IMPORTANT] Resolução de Conflito de Porta: A porta padrão
5432da VM já estava ocupada por um banco de dados local (vaideferry-db). O HDT-AF isola seu PostgreSQL na porta de host15432:5432.
3. Pré-requisitos e Preparação do Ambiente¶
3.1 Espaço em Disco na VM¶
A imagem Docker multi-módulo do HDT-AF com OpenJDK 25 requer cerca de 1,6 GB. Antes da implantação, garanta que a partição raiz / possua pelo menos 4 GB livres:
# Limpeza de imagens órfãs e cache de build
ssh josedaniel@192.168.10.198 "docker image prune -f && docker builder prune -f"
df -h /
3.2 Rede Hyperledger Fabric Ativa¶
Verifique se a rede Fabric e o chaincode estão ativos na VM antes de subir a stack da aplicação:
Para inspecionar o chaincode committed no canal:
ssh josedaniel@192.168.10.198 "docker exec peer0.org1.example.com peer lifecycle chaincode querycommitted -C federated-channel"
Committed chaincode definition for chaincode 'federated-governance' on channel 'federated-channel': Version: 1.1, Sequence: 2.
4. Procedimento de Implantação Passo a Passo¶
Passo 1: Construção da Imagem Multi-Plataforma (linux/amd64)¶
O host de compilação (ex.: macOS Apple Silicon) requer o uso de docker buildx para gerar a imagem compatível com a arquitetura linux/amd64 da VM:
docker buildx build \
--platform linux/amd64 \
-t hdt-af:latest \
-f docker/Dockerfile.app \
--load .
[!NOTE] O arquivo
docker/Dockerfile.appcompila os 22 módulos do reactor Maven com JDK 25 utilizando os parâmetros-Dspotbugs.skip=true -Dcheckstyle.skip=true, prevenindo exceções de versão de bytecode (ASM major version 69).
Passo 2: Transferência Direta da Imagem via Stream SSH¶
Para evitar dependência de registro externo privado ou falta de código-fonte completo na VM, transfira a imagem compactada diretamente para o daemon Docker da VM:
Passo 3: Provisionamento de Credenciais e Configurações¶
No diretório de execução na VM (/home/josedaniel/hdt-af/):
- Credenciais do Hyperledger Fabric:
Copie os certificados de identidade do administrador Org1 para a pasta
fabric-credentials/: Admin@org1.example.com-cert.pemAdmin@org1.example.com-key.pemtlsca.org1.example.com-cert.pem- Certificados MQTT TLS:
Sincronize a pasta
deploy/mqtt/tls/contendomqtt-truststore.p12emqtt-client.p12. - Especificações de Experimento:
Sincronize
research/experiments/para montagem dos manifests de pesquisa.
Passo 4: Execução via Docker Compose¶
Utilize a configuração padronizada de docker/docker-compose.vm.yml:
5. Arquivo de Configuração de Produção (docker-compose.yml)¶
O arquivo aplicado na VM possui a seguinte estrutura:
name: hdt-af
services:
# ── Broker MQTT 5 ────────────────────────────────────────────────────────────
mosquitto:
image: eclipse-mosquitto:2
restart: unless-stopped
ports:
- "1883:1883"
- "8883:8883"
- "9001:9001"
volumes:
- ./docker/mosquitto/mosquitto.conf:/mosquitto/config/mosquitto.conf:ro
- ./deploy/mqtt/tls:/mosquitto/config/tls:ro
- mosquitto-data:/mosquitto/data
- mosquitto-log:/mosquitto/log
networks:
- hdt-net
healthcheck:
test: ["CMD-SHELL", "mosquitto_pub -h localhost -p 8883 --cafile /mosquitto/config/tls/ca.crt --cert /mosquitto/config/tls/client.crt --key /mosquitto/config/tls/client.key -t _health -m ok -q 0 2>/dev/null || mosquitto_pub -h localhost -p 1883 -t _health -m ok -q 0 2>/dev/null && echo ok"]
interval: 10s
timeout: 5s
retries: 5
# ── Banco de Dados Local CDM (PostgreSQL) ────────────────────────────────────
postgres:
image: postgres:16-alpine
restart: unless-stopped
environment:
POSTGRES_DB: federated_local_cdm
POSTGRES_USER: ${POSTGRES_USER:-hdt_af}
POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-hdt_af_secret}
volumes:
- postgres-data:/var/lib/postgresql/data
ports:
- "${POSTGRES_HOST_PORT:-15432}:5432"
networks:
- hdt-net
healthcheck:
test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-hdt_af} -d federated_local_cdm"]
interval: 10s
timeout: 5s
retries: 5
# ── Monitor Web (Admin API) — porta 8088 ─────────────────────────────────────
hdt-af-admin:
image: hdt-af:latest
restart: unless-stopped
environment:
MAIN_CLASS: br.ufma.lsdi.admin.AdminWebApp
FEDERATED_LEDGER_MODE: blockchain
LGPD_PSEUDONYM_SALT: ${LGPD_PSEUDONYM_SALT:-b9204f2f56748d453d5d820c219801fe633b5ad5b572550ad7c885b1297510b6}
ROUND_DEADLINE_SECONDS: 120
MQTT_BROKER_URL: ssl://mosquitto:8883
MQTT_TLS_TRUSTSTORE: /app/mqtt-tls/mqtt-truststore.p12
MQTT_TLS_TRUSTSTORE_PASSWORD: changeit
MQTT_TLS_KEYSTORE: /app/mqtt-tls/mqtt-client.p12
MQTT_TLS_KEYSTORE_PASSWORD: changeit
MQTT_CLIENT_ID: hdt-af-admin
HDT_AF_DATA_ROOT: /app/data
HDT_AF_ARTIFACT_ROOT: /app/artifacts
HDT_AF_RESEARCH_ROOT: /app/research
ADMIN_STATIC_ROOT: /app/static
# Hyperledger Fabric Gateway
FABRIC_CHANNEL_NAME: federated-channel
FABRIC_CHAINCODE_NAME: federated-governance
FABRIC_FAIL_ON_ERROR: "false"
FABRIC_GATEWAY_PEER_ENDPOINT: peer0.org1.example.com:7051
FABRIC_GATEWAY_TLS_SERVER_NAME_OVERRIDE: peer0.org1.example.com
FABRIC_GATEWAY_TLS_CERT_PATH: /app/fabric/tlsca.org1.example.com-cert.pem
FABRIC_GATEWAY_MSP_ID: Org1MSP
FABRIC_GATEWAY_CERT_PATH: /app/fabric/Admin@org1.example.com-cert.pem
FABRIC_GATEWAY_KEY_PATH: /app/fabric/Admin@org1.example.com-key.pem
ports:
- "8088:8088"
volumes:
- ./data:/app/data
- ./target/artifacts:/app/artifacts
- ./deploy/mqtt/tls:/app/mqtt-tls:ro
- ./logs:/app/logs
- ./static:/app/static
- ./fabric-credentials:/app/fabric:ro
depends_on:
mosquitto:
condition: service_healthy
postgres:
condition: service_healthy
networks:
- hdt-net
- fabric_test
volumes:
mosquitto-data:
mosquitto-log:
postgres-data:
networks:
hdt-net:
driver: bridge
fabric_test:
external: true
6. Verificação de Funcionamento e Diagnóstico¶
6.1 Status dos Contêineres¶
Saída esperada: -hdt-af-hdt-af-admin-1: Status Up (porta 0.0.0.0:8088->8088/tcp)
- hdt-af-mosquitto-1: Status Up (healthy) (portas 1883, 8883, 9001)
- hdt-af-postgres-1: Status Up (healthy) (porta 0.0.0.0:15432->5432/tcp)
6.2 Teste do Monitor Web (HTTP 200)¶
Saída esperada:200 (renderiza o dashboard HTML interativo).
6.3 Teste da REST API de Experimentos¶
Saída esperada: JSON contendo os experimentos registrados e auditados na rede Fabric (exp-dt-federated-001, exp-har-smartphones-001, exp-ecg5000-anomaly-001).
7. Lições Aprendidas e Resolução de Problemas (Troubleshooting)¶
Erro 1: Incompatibilidade do SpotBugs com Java 25¶
- Sintoma:
IllegalArgumentException: Unsupported class file major version 69durante omvn install. - Causa: A versão do SpotBugs utilizada não reconhece o bytecode de classes do JDK 25.
- Solução: Desabilitar temporariamente a análise do SpotBugs e Checkstyle na montagem da imagem de produção via
-Dspotbugs.skip=true -Dcheckstyle.skip=truenoDockerfile.app.
Erro 2: Colisão da Porta 5432 do PostgreSQL¶
- Sintoma:
bind: address already in useao subir o contêinerpostgres. - Causa: Existência prévia do contêiner
vaideferry-dbvinculado a0.0.0.0:5432no host da VM. - Solução: Remapear a porta no host para
15432:5432através da variávelPOSTGRES_HOST_PORT: 15432.
Erro 3: Erro 503 ("Frontend não construído")¶
- Sintoma: Acesso à raiz
GET /retornava código 503 com mensagem de frontend não construído. - Causa:
ADMIN_STATIC_ROOTapontava para um caminho SPA inexistente (/app/modules/federated-admin-web/dist). - Solução: Configurar
ADMIN_STATIC_ROOT: /app/statice montar diretório vazio./static:/app/static. OAdminWebServer(linhas 3718-3720) detecta a ausência deindex.htmlestático e ativa automaticamente o dashboard HTML renderizado viaAdminHtmlLayout.
Erro 4: Falha na Resolução de Nomes do Hyperledger Fabric¶
- Sintoma: Falha de conexão gRPC com
peer0.org1.example.com. - Causa: O contêiner da aplicação estava apenas na rede
hdt-net, incapaz de resolver os hostnames da redefabric_test. - Solução: Adicionar a rede externa
fabric_testao contêinerhdt-af-adminno Compose. O DNS interno do Docker roteia diretamente os pacotes gRPC para a porta7051do peer.