Ir para o conteúdo

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):

  1. hdt-net (Bridge interna gerenciada pelo Docker Compose):
  2. Conecta hdt-af-admin, mosquitto e postgres.
  3. Permite resolução de nomes interna por serviço (mosquitto:8883, postgres:5432).
  4. fabric_test (Bridge externa gerenciada pela rede Fabric):
  5. Conecta hdt-af-admin aos peers e orderer do consórcio.
  6. 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 5432 da VM já estava ocupada por um banco de dados local (vaideferry-db). O HDT-AF isola seu PostgreSQL na porta de host 15432: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:

ssh josedaniel@192.168.10.198 "docker ps --filter 'name=peer0.org1'"

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"
Saída esperada: 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.app compila 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:

docker save hdt-af:latest | gzip | ssh josedaniel@192.168.10.198 "gunzip | docker load"

Passo 3: Provisionamento de Credenciais e Configurações

No diretório de execução na VM (/home/josedaniel/hdt-af/):

  1. Credenciais do Hyperledger Fabric: Copie os certificados de identidade do administrador Org1 para a pasta fabric-credentials/:
  2. Admin@org1.example.com-cert.pem
  3. Admin@org1.example.com-key.pem
  4. tlsca.org1.example.com-cert.pem
  5. Certificados MQTT TLS: Sincronize a pasta deploy/mqtt/tls/ contendo mqtt-truststore.p12 e mqtt-client.p12.
  6. 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:

cd /home/josedaniel/hdt-af
docker compose -f docker-compose.yml up -d

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

docker compose ps
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)

curl -s -o /dev/null -w "%{http_code}\n" http://192.168.10.198:8088/
Saída esperada: 200 (renderiza o dashboard HTML interativo).

6.3 Teste da REST API de Experimentos

curl -s http://192.168.10.198:8088/api/experiments | jq .
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 69 durante o mvn 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=true no Dockerfile.app.

Erro 2: Colisão da Porta 5432 do PostgreSQL

  • Sintoma: bind: address already in use ao subir o contêiner postgres.
  • Causa: Existência prévia do contêiner vaideferry-db vinculado a 0.0.0.0:5432 no host da VM.
  • Solução: Remapear a porta no host para 15432:5432 através da variável POSTGRES_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_ROOT apontava para um caminho SPA inexistente (/app/modules/federated-admin-web/dist).
  • Solução: Configurar ADMIN_STATIC_ROOT: /app/static e montar diretório vazio ./static:/app/static. O AdminWebServer (linhas 3718-3720) detecta a ausência de index.html estático e ativa automaticamente o dashboard HTML renderizado via AdminHtmlLayout.

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 rede fabric_test.
  • Solução: Adicionar a rede externa fabric_test ao contêiner hdt-af-admin no Compose. O DNS interno do Docker roteia diretamente os pacotes gRPC para a porta 7051 do peer.