Documentação Técnica — ecosif-structure

Público-alvo: Desenvolvedores / SRE
Módulo: ecosif-structure (orquestração Docker)

1. Visão Geral

O ecosif-structure é o projeto de orquestração do ecossistema ds-ecosif. Define a topologia de rede, os serviços Docker e o reverse proxy (Traefik) que permitem que todos os módulos (PostgreSQL, ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports, ecosif-compliance, ecosif-angular) comuniquem entre si e sejam acessíveis através de um único domínio.

2. Topologia de Rede (docker-compose)

2.1 Rede Única

Todos os serviços pertencem à mesma rede bridge definida no docker-compose.yml:

networks:
  ecosif-network:
    driver: bridge

Cada container resolve os outros pelo nome do serviço (ex.: postgres, ecosif-auth, ecosif-masterdata). Não é necessário usar IPs nem portas expostas no host para comunicação entre serviços.

2.2 Comunicação Entre Containers

Origem	Destino	Como se conecta
Qualquer serviço	PostgreSQL	Host: `postgres`, Porta: `${POSTGRES_PORT:-5432}` (ex.: `postgres:5432`)
Traefik	Qualquer serviço backend	Nome do serviço + porta interna (ex.: `ecosif-auth:8080`)
ecosif-angular (browser)	Backends	Via domínio (Traefik); no browser as chamadas vão ao mesmo host (ex.: `https://dominio/ecosif-auth`)
Scripts no host	PostgreSQL	`localhost:5432` se a porta estiver mapeada; ou `docker exec postgres ...`

Exemplo de variáveis nos serviços Spring Boot:

POSTGRES_HOST=postgres (nunca localhost dentro do container)
POSTGRES_PORT=${POSTGRES_PORT:-5432}

2.2.1 Convenção de Variáveis por Módulo

No ecosif-structure, os serviços seguem a convenção:

Porta interna: ECOSIF_<SERVICO>_PORT
Context path: ECOSIF_<SERVICO>_CONTEXT_PATH
URLs do Angular: ECOSIF_ANGULAR_API_* (com derivação automática dos context paths)

Exemplos:

ECOSIF_AUTH_PORT + ECOSIF_AUTH_CONTEXT_PATH
ECOSIF_MASTERDATA_PORT + ECOSIF_MASTERDATA_CONTEXT_PATH
ECOSIF_COMPLIANCE_PORT + ECOSIF_COMPLIANCE_CONTEXT_PATH

Para o ecosif-compliance, o compose mapeia POSTGRES_* para as variáveis internas ECOSIF_DB_*, mantendo compatibilidade sem duplicar configuração de banco no .env.

2.3 Diagrama de Rede (Mermaid)

flowchart TB
    subgraph Internet["Internet / Cliente"]
        User[Browser / Cliente]
    end

    subgraph Traefik["Traefik (80, 443, 8080)"]
        T[Traefik]
    end

    subgraph ecosif_network["Rede: ecosif-network"]
        PG[(postgres:5432)]
        AUTH[ecosif-auth]
        MD[ecosif-masterdata]
        MOV[ecosif-moviments]
        Q[ecosif-querys]
        RPT[ecosif-reports]
        CMP[ecosif-compliance]
        ANG[ecosif-angular]
    end

    User -->|HTTPS/HTTP| T
    T -->|PathPrefix /ecosif-auth| AUTH
    T -->|PathPrefix /ecosif-masterdata| MD
    T -->|PathPrefix /ecosif-moviments| MOV
    T -->|PathPrefix /ecosif-querys| Q
    T -->|PathPrefix /ecosif-reports| RPT
    T -->|PathPrefix /ecosif-compliance| CMP
    T -->|Resto (SPA)| ANG

    AUTH --> PG
    MD --> PG
    MOV --> PG
    Q --> PG
    RPT --> PG
    CMP --> PG

2.4 Portas Expostas no Host

Porta	Serviço	Uso
80	Traefik	HTTP (dev ou redirect)
443	Traefik	HTTPS
8080	Traefik	Dashboard Traefik
5432	postgres	PostgreSQL (opcional; para acesso externo ou scripts)
8080–8084, 8021	Backends	Opcional; cada serviço pode expor a sua porta (definida no .env)

Acesso externo ao utilizador é feito só pelas portas 80/443; Traefik encaminha por path (ECOSIF_*_CONTEXT_PATH) para o container correto.

2.5 Modo Desenvolvimento (docker-compose.dev.yml)

Sobrescreve os entrypoints do Traefik para web (HTTP) em vez de websecure (HTTPS).
Serviços usam traefik.http.routers.*.entrypoints=web e tls=false.
Traefik usa traefik.dev.yml; dashboard em HTTP.

Uso: docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d.

3. Volumes e Persistência

Volume	Serviço	Uso
postgres_data	postgres	Dados do PostgreSQL (`/var/lib/postgresql/data`)
traefik_acme	traefik	Certificados Let's Encrypt (ACME)
/etc/letsencrypt (host)	traefik	Certificados montados no container (rw para renovação)
./logs/compliance	ecosif-compliance	Logs do serviço de compliance
/var/run/docker.sock (ro)	ecosif-masterdata	Acesso ao Docker (conforme necessidade do serviço)

Os scripts de Primeira Instalação (ex.: init-database.sh) garantem que o banco existe e que as migrations são aplicadas; o volume postgres_data persiste entre restarts.

4. Ordem de Arranque e Dependências

postgres: Sem dependências; tem healthcheck com pg_isready.
ecosif-auth, ecosif-masterdata, ecosif-moviments, ecosif-querys, ecosif-reports: depends_on: postgres: condition: service_healthy.
ecosif-compliance: depends_on: postgres: condition: service_healthy.
ecosif-angular: Sem dependência de outros serviços (serve estáticos; APIs chamadas pelo browser via Traefik).
traefik: Sem dependências; outros serviços registam-se via labels.

O script start.sh sobe todos com docker compose up -d; o healthcheck do Postgres garante que os serviços Java/Python só arrancam depois do banco estar pronto.

5. Traefik e Labels

Cada serviço (exceto postgres) que deve ser acessível via Traefik tem labels como:

traefik.enable=true
traefik.http.routers.<nome>.rule=Host(...) && PathPrefix(...)
traefik.http.routers.<nome>.entrypoints=websecure (ou web em dev)
traefik.http.services.<nome>.loadbalancer.server.port=<porta>

O ecosif-angular tem prioridade 0 e regra que exclui os PathPrefix dos backends, para que o SPA receba todo o tráfego que não for para /ecosif-auth, /ecosif-masterdata, etc.

Para mais detalhes de operação (primeira instalação, scripts, variáveis) e visão para o gestor (serviços, saúde), consulte operacao.md e user/visao_geral.md.