Deploy AWS ECS + API Gateway — ecosif-angular

Público-alvo: DevOps / SRE
Índice: README.md
Objetivo: Configurar o frontend eCosif na AWS usando ECS e uma única API Gateway com múltiplos mapeamentos. O domínio final é app.ecosif.com.br (frontend na raiz; backends em app.ecosif.com.br/[módulo]).

Este documento não cobre criação de banco de dados (pressupõe que o banco já existe noutro recurso).

1. Arquitetura geral

• Domínio: https://app.ecosif.com.br
• Frontend (SPA): servido na raiz https://app.ecosif.com.br (e paths não reservados para APIs).
• Backends: um path por serviço, na mesma origem:
• https://app.ecosif.com.br/ecosif-auth
• https://app.ecosif.com.br/ecosif-masterdata
• https://app.ecosif.com.br/ecosif-moviments
• https://app.ecosif.com.br/ecosif-querys
• https://app.ecosif.com.br/ecosif-reports
• https://app.ecosif.com.br/ecosif-compliance
• https://app.ecosif.com.br/ecosif-automations (se expuser API HTTP)

Uma única API Gateway (REST ou HTTP API) faz o roteamento por path para os respetivos targets (ALB dos serviços ECS ou integração HTTP direta).

2. Mapeamento na API Gateway

A ordem das rotas na API Gateway deve dar prioridade aos paths mais específicos (/ecosif-auth, etc.) e deixar o default (/) para o frontend.

3. ecosif-angular (frontend) no ECS

3.1 Papel no desenho

• O frontend é servido como ficheiros estáticos (build Angular) por um contentor Nginx (ou similar) atrás de um ALB, ou por CloudFront + S3 com fallback para o mesmo ALB.
• O browser acede sempre a https://app.ecosif.com.br. As chamadas às APIs são feitas para a mesma origem (ex.: https://app.ecosif.com.br/ecosif-auth/...), pelo que CORS para o próprio domínio pode ser apenas https://app.ecosif.com.br.

3.2 Variáveis de ambiente (build e runtime)

Configuração em build (Docker/CI) e/ou em runtime via window.env (ex.: env.js injetado no contentor).

Importante: Em produção com domínio único, não é necessário definir ECOSIF_API_BASE_URL no frontend; as bases das APIs são apenas os paths relativos acima (ex.: /ecosif-auth), pois o browser usa sempre https://app.ecosif.com.br.

3.3 Exemplo de configuração runtime (env.js)

Para o contentor que serve o Angular, o script que gera window.env pode expor:

window.env = {
  authUrl: '/ecosif-auth',
  apiUrl: '/ecosif-masterdata',
  movementAPIUrl: '/ecosif-moviments',
  entryAPIUrl: '/ecosif-querys',
  reportsApiUrl: '/ecosif-reports',
  complianceApiUrl: '/ecosif-compliance',
  production: true,
  debug: false,
  paginationSize: 100
};

3.4 ECS (task definition)

• Imagem: build do Angular com Nginx (ex.: Dockerfile.prod do projeto).
• Porta do contentor: 80 (Nginx).
• Variáveis de ambiente na task: conforme tabela acima, se o entrypoint do contentor gerar env.js a partir delas.
• Health check: path configurado no Nginx (ex.: /health) → 200.

Para mais detalhes de build, Nginx e variáveis, ver docker.md.

4. Certificado digital no endereço do API Gateway

O endereço correto que o utilizador usa é o domínio customizado (ex.: app.ecosif.com.br). O certificado SSL/TLS é associado a esse domínio no API Gateway, não no contentor do Angular nem nos ALBs. O fluxo é: Cliente (HTTPS) → API Gateway (domínio + certificado) → rotas por path → ALB → ECS.

4.1 Visão geral dos passos

1. Obter um certificado para o domínio no AWS Certificate Manager (ACM).
2. Criar um domínio customizado no API Gateway e anexar o certificado a esse domínio.
3. Mapear o domínio customizado para a sua API (REST ou HTTP API).
4. DNS: apontar o nome do domínio (ex.: app.ecosif.com.br) para o endpoint do domínio customizado do API Gateway.

Assim, todo o tráfego em https://app.ecosif.com.br usa o certificado configurado no API Gateway e é roteado para os targets (frontend na /, backends nos paths /ecosif-*).

4.2 Passo 1 — Certificado no ACM

1. No AWS Console → Certificate Manager (ACM) (na mesma região onde vai criar o API Gateway).
2. Request a certificate: - Fully qualified domain name: o domínio que vai usar (ex.: app.ecosif.com.br ou *.ecosif.com.br para wildcard). - Validation method: DNS validation (recomendado) ou Email validation.
3. Se escolher DNS validation: na lista de certificados, abra o certificado e crie os registos CNAME indicados na sua zona DNS (Route 53 ou DNS externo) até o estado ficar Issued.

Nota: O certificado deve estar na mesma região que o API Gateway. Para API Gateway REST API use a região onde a API está; para HTTP API o domínio customizado pode usar certificado em us-east-1 (requisito da AWS para edge-optimized).

4.3 Passo 2 — Domínio customizado no API Gateway

Opção A — API Gateway HTTP API (recomendado para novo desenho)

1. API Gateway → Custom domain names (no menu da HTTP API).
2. Create domain name: - Domain name: ex. app.ecosif.com.br. - Domain name configuration: Import certificate ou ACM certificate (selecione o certificado do ACM criado no passo 1). - Endpoint type: Regional (recomendado; o certificado pode estar na mesma região da API).
3. Guarde o API Gateway domain name (ex.: d-xxxxxxxxxx.execute-api.region.amazonaws.com) e o Target domain name que a AWS mostrar para o custom domain — será usado no DNS.

Opção B — API Gateway REST API

1. API Gateway → Custom domain names (na secção da REST API).
2. Create: - Domain name: ex. app.ecosif.com.br. - Regional certificate: selecione o certificado do ACM (na mesma região da API). - Ou use Edge-optimized e um certificado em us-east-1.
3. Depois de criar, em API mappings associe este domínio à sua REST API e ao stage (ex.: prod).

4.4 Passo 3 — Mapear o domínio à API

• HTTP API: Em Custom domain names → selecione o domínio → Configure API mappings → adicione um mapping: API = sua HTTP API, Stage = ex. $default ou prod. Defina as rotas na API (path / → integração com ALB do frontend; paths /ecosif-auth, /ecosif-auth/{proxy+}, etc. → ALB dos backends).
• REST API: No domínio customizado, API mappings → Add new mapping → API = sua REST API, Stage = ex. prod. As rotas já estão definidas nos resources da REST API (recursos /, /ecosif-auth, /ecosif-auth/{proxy+}, etc., com integração HTTP para os ALBs).

Cada integração HTTP deve apontar para o ALB do respetivo serviço ECS (frontend para o ALB do ecosif-angular; backends para os ALBs de ecosif-auth, ecosif-masterdata, etc.). A ordem das rotas deve dar prioridade aos paths mais específicos (/ecosif-auth, etc.) e deixar / (e catch-all) para o frontend.

4.5 Passo 4 — DNS: apontar o domínio para o API Gateway

Para o endereço final ser https://app.ecosif.com.br com o certificado ativo:

1. Na zona DNS do domínio (ex.: Route 53 ou provedor externo), crie um registo que aponte o nome (ex.: app.ecosif.com.br) para o target do domínio customizado do API Gateway: - Route 53: Crie um registo A (Alias) ou CNAME apontando para o target do custom domain (a AWS mostra esse valor em Custom domain names → seu domínio → Configuration). - DNS externo: Normalmente um CNAME de app.ecosif.com.br para o valor Target domain name mostrado no API Gateway (ex.: d-xxxxxxxxxx.execute-api.region.amazonaws.com ou o endpoint regional indicado).
2. Aguarde a propagação DNS (minutos a algumas horas).

4.6 Resumo

Assim, o certificado digital fica no endereço correto — no domínio do API Gateway que o utilizador usa para aceder ao frontend e às APIs. O contentor do ecosif-angular continua a servir apenas HTTP (porta configurada em AngularPort / ECOSIF_ANGULAR_PORT) atrás do ALB; o HTTPS é terminado no API Gateway com o certificado que configurou.

5. Documentação relacionada

Materiais internos (guia cliente, Fargate aprofundado): .internal_docs/ (local, não versionado) — ver README.md.