Entender a hospedagem de apps e como ela funciona

O App Hosting processa uma série complexa de tarefas em segundo plano para simplificar a implantação do app. Esta página descreve as partes principais desse fluxo de tarefas, fornecendo informações sobre pontos em que você pode personalizar o fluxo dependendo das necessidades do app.

Integração de framework

O App Hosting oferece suporte pré-configurado para build e implantação de apps da Web desenvolvidos nestes frameworks:

  • Next.js 13+
  • Angular 17.2 ou mais recente

O App Hosting identifica qual framework você está usando ao inspecionar o arquivo package-lock.json ou outro arquivo de bloqueio no repositório. Se você tentar implantar um app Node.js que não tem um arquivo de bloqueio, o App Hosting não vai conseguir criar e executar o app. É possível criar package-lock.json executando npm install no diretório raiz.

Adaptadores de framework

Os adaptadores de framework App Hosting têm duas funções principais:

  1. Eles analisam o código-fonte e qualquer arquivo de configuração específico do framework (como next.config.js) e geram um pacote de saída que pode ser processado pelo restante da infraestrutura do App Hosting.
  2. Eles executam o comando de build do app para gerar recursos estáticos e criar uma versão otimizada do app para produção.

Os adaptadores de framework criam seu app Node.js com npm run build, funcionando melhor com os scripts de build padrão de cada framework: next build para Next.js e ng build para Angular. O App Hosting vai tentar criar builds com comandos de build personalizados, mas não pode garantir o sucesso.

A origem dos adaptadores do Next.js e do Angular está disponível em firebase-framework-tools.

Outras estruturas

Além do Next.js e do Angular, o App Hosting também oferece suporte a qualquer framework da Web que for capaz de fornecer uma saída de build que corresponda à nossa especificação de pacote de saída. Os autores de frameworks podem aproveitar a especificação do pacote de saída para garantir que o framework tenha suporte ao Hospedagem de apps.

Se você quiser que outros frameworks sejam aceitos, crie um adaptador ou entre em contato com os mantenedores do framework para converter as saídas de build no formato de hospedagem de apps. Os adaptadores Next.js e Angular são bons exemplos de referência para quem está criando um adaptador.

Os frameworks compatíveis podem ser encontrados no Firebase Open Source.

Como funciona a integração do repositório App Hosting

A conexão importante entre seu repositório do GitHub e o back-end do App Hosting é gerenciada pelo Developer Connect, a plataforma de conectividade do Google Cloud para ferramentas externas de DevOps. Durante a criação de um back-end App Hosting, o fluxo de trabalho da interface do Developer Connect orienta você na instalação do app GitHub do Firebase. As principais etapas desse processo são:

  1. Você concede ao Developer Connect o papel de Administrador do Secret Manager. Isso permite que o sistema armazene credenciais com segurança como "secrets" no Cloud Secret Manager.
  2. Você autoriza o app GitHub do Firebase a acessar seu repositório do GitHub.
  3. O Developer Connect armazena um token de autorização do GitHub dedicado no repositório do gerenciador de segredos do projeto. Não modifique nem exclua esse token.

Além disso, App Hosting se integra à API GitHub Checks para verificar os lançamentos. Essa verificação permite conferir o status do lançamento no GitHub e depurar o processo de implantação em caso de erros.

Integração com o Firebase e outros serviços do Google

App Hosting configura os ambientes de build e de execução para que você possa inicializar o SDK Admin do Firebase com as Application Default Credentials do Google. Dessa forma, o back-end pode se comunicar com outros produtos do Firebase durante a criação e o deploy.

App Hosting locais

A implantação de App Hosting cria os recursos de back-end em um local específico. Essa flexibilidade no local do app da Web tem vantagens importantes:

  • Melhoria no desempenho e redução da latência ao deixar os dados geograficamente mais próximos dos usuários.
  • Uma falha catastrófica de App Hosting em uma região não afetaria apps da Web implantados em outras regiões.

É possível escolher qualquer uma dessas regiões ao criar um back-end do App Hosting no console ou na CLI Firebase:

  • us-central1 (Iowa)
  • asia-east1 (Taiwan)
  • europe-west4 (Países Baixos)

A conta de serviço de back-end App Hosting

Durante o build e no momento da execução, o back-end do App Hosting se autentica com outros serviços do Google com uma conta de serviço. Uma conta de serviço padrão para esses fins é criada na primeira vez que você ativa App Hosting em um projeto do Firebase:

firebase-app-hosting-compute@PROJECT ID.iam.gserviceaccount.com

Essa conta de serviço se aplica a todos os back-ends por padrão e tem um conjunto mínimo de permissões para criar, executar e monitorar seu app. Ela também tem permissão para autenticar o SDK Admin com as credenciais padrão do aplicativo para realizar operações como o carregamento de dados de Cloud Firestore. Consulte Papéis do App Hosting do Firebase.

Se o app precisar interagir com outros serviços do Google no momento do build ou em um back-end em execução, será possível personalizar a conta de serviço padrão adicionando papéis. Por exemplo, se o app exigir permissões para a Vertex AI, talvez seja necessário adicionar roles/aiplatform.user ou algum papel relacionado.

Principais termos e definições

  • Back-end: a coleção de recursos gerenciados que o App Hosting cria para desenvolver e executar seu app da Web.
  • Implementação: uma versão específica do app em uso, vinculada a um commit do Git.
  • Branch ativo: o branch do repositório do GitHub que é implantado no URL ativo. Geralmente, é a ramificação em que as ramificações de recursos ou de desenvolvimento são mescladas.

Limitações e problemas conhecidos

A visualização de App Hosting tem algumas limitações conhecidas:

  • Em alguns casos, um back-end App Hosting pode retornar mensagens Intermittent connection error no URL do app. Uma correção vai estar disponível em uma versão futura.
  • Os cabeçalhos Cache-Control são modificados para limitar os caches do CDN a 60 segundos. No futuro, quando o App Hosting puder limpar rapidamente o cache na implantação, esse limite será removido.
  • A otimização de imagens é feita em Cloud Run por padrão, e as imagens otimizadas não são mantidas. Recomendamos desativar a otimização de imagens ou especificar manualmente um carregador até que uma solução melhor esteja disponível.
  • Os arquivos estáticos não armazenados em cache são veiculados fora de Cloud Run. Em uma versão posterior, eles serão armazenados e veiculados da origem App Hosting para melhorar o desempenho.
  • Os SKUs do App Hosting podem não aparecer na página de uso do back-end no console Firebase. Eles vão estar disponíveis em uma versão futura.
  • O console Firebase pode mostrar intermitentemente um erro "build não encontrado e inválido" na criação do back-end.
  • Atualmente, todos os back-ends no mesmo projeto compartilham uma organização/conta do GitHub. Eles podem ser conectados a diferentes repositórios nessa organização/conta. Para criar back-ends conectados a diferentes contas do GitHub, coloque-os em projetos separados.
  • Os middlewares, as reescritas e os redirecionamentos do Next.js são executados em Cloud Run, atrás do CDN. Como elas não protegem as respostas em cache, defina diretivas de controle adequadas para o conteúdo que você está renderizando.