Ahtesham-Latif/Tie-Breaker-App

Implantação no Azure App Service (Node.js)

Esta skill descreve o caminho impecável e de melhores práticas para implantar uma aplicação Node.js no Azure App Service (Linux), conectando-se com segurança a um agente do Azure AI Foundry via Managed Identity.

1. Configuração da Infraestrutura em Nuvem

• Plano do App Service: Sempre escolha um nível dedicado (ex.: Básico B1) para produção. Níveis gratuitos (F1) têm cotas rigorosas de 60 minutos diários de CPU que forçarão o desligamento da aplicação (resultando em um erro 403 Stopped).

2. Autenticação e Managed Identity (Sem Senha)

1. Código: Use DefaultAzureCredential do pacote @azure/identity no backend Node.js.
2. Habilitar Identidade: No portal do Azure App Service, vá em Configurações > Identidade e habilite Atribuída pelo sistema.
3. Permissões IAM: No projeto Azure AI de destino, vá em Controle de acesso (IAM) e atribua a função Azure AI Developer à Identidade Gerenciada do App Service. (Nota: Cognitive Services OpenAI User não é suficiente para Agentes de Orquestração do Azure Foundry).

3. Variáveis de Ambiente (A Armadilha Frontend vs Backend)

Ao implantar uma aplicação full-stack (React/Vite + Node.js) via GitHub Actions, as variáveis de ambiente devem ser separadas logicamente:

O Frontend (Vite)

• Variáveis prefixadas com VITE_ (ex.: chaves do Supabase) são incorporadas ao HTML/JS estático no momento da build.
• Onde defini-las: Elas DEVEM ser armazenadas em Segredos do GitHub e mapeadas explicitamente no arquivo .github/workflows dentro do bloco env: para a etapa npm run build.
• Perigo: Se estiverem apenas no Azure e não no GitHub Actions, o Vite construirá o frontend com variáveis vazias.

O Backend (Node.js)

• O arquivo server.js ativo lê as variáveis de ambiente em tempo de execução a partir do contêiner da nuvem.
• Onde defini-las: Configure variáveis (ex.: endpoints do Azure AI, chaves do Supabase para o backend) diretamente no Portal do Azure em Configurações > Variáveis de ambiente.
• Perigo: O backend do Azure App Service NÃO herda os segredos do GitHub Actions. Você deve defini-los manualmente no Portal do Azure.
• Crucial: As variáveis são carregadas na memória exatamente uma vez, quando o processo Node.js é iniciado. Se uma variável for adicionada ou alterada, você deve clicar explicitamente em Reiniciar na página de Visão Geral do App Service.
• Para confiar no Balanceador de Carga do Azure (necessário para express-rate-limit), garanta que o aplicativo Express tenha app.set('trust proxy', 1);.

4. Pipeline CI/CD do GitHub Actions

A estratégia de implantação mais segura evita conflitos entre mecanismos de build (GitHub vs. Azure Oryx). Deixe o GitHub fazer 100% da construção e empacotamento.

Melhores Práticas do Workflow:

1. O GitHub executa npm install e a build do frontend (npm run build).
2. O GitHub faz upload de um artefato contendo a saída compilada (dist), os arquivos do backend (server.js) e, crucialmente, a pasta node_modules.
   • Por quê? Se node_modules for omitido, o mecanismo Oryx do Azure tentará construir a aplicação executando npm run build, o que falhará porque os arquivos fonte brutos (index.html) não foram enviados.
3. Use azure/webapps-deploy@v3 com um Perfil de Publicação armazenado como um Segredo do GitHub.