Formas alternativas de implantar no App Hosting

Na maioria das vezes, recomendamos usar rollouts automáticos ou acionados manualmente no console Firebase. No entanto, talvez você tenha um uso para um fluxo de implantação mais personalizado. O App Hosting tem várias opções de implantação personalizada.

Implantar a partir da origem

A implantação da origem permite enviar o código-fonte e a configuração do aplicativo diretamente para o App Hosting sem exigir uma conexão persistente do GitHub.

Ao implantar do código-fonte, o App Hosting faz upload do código-fonte para um bucket Google Cloud Storage, executa o comando de build do framework em Cloud Build e implanta os artefatos compilados no Cloud Run e no Cloud CDN. O mesmo processo de build é usado para implantações de origem local e do GitHub. Se um arquivo .gitignore estiver presente no projeto, os arquivos e pastas listados nele serão excluídos da implantação.

É possível fazer a implantação de uma origem local usando a CLI Firebase ou o console Firebase.

Permissões do IAM obrigatórias e configuração da infraestrutura

Como a CLI Firebase e o console Firebase usam a mesma infraestrutura de back-end para armazenar e criar seus arquivos de origem, os mesmos requisitos de permissão do IAM se aplicam aos dois métodos de implantação.

Os requisitos exatos dependem de você estar implantando em um local (região) específico pela primeira vez. Para mais informações sobre permissões, consulte a visão geral do IAM do Firebase e as permissões específicas do Firebase App Hosting.

Permissões para integração inicial (primeira implantação em um local)

Quando a implantação de origem local é iniciada em um local de projeto pela primeira vez, o Hosting precisa provisionar um bucket do GCS para armazenar seus arquivos e conceder ao agente de serviço do Hosting acesso a eles. Como essas são tarefas administrativas para envolvidos no projeto, elas exigem permissões de Proprietário do projeto ou administrador do IAM. Um usuário com uma função básica de editor ou leitor não pode fazer essa configuração inicial e será bloqueado.

As permissões de configuração de pré-requisito incluem:

  • Ativar a API Storage: serviceusage.services.enable
  • Criar bucket de origem: storage.buckets.create e storage.buckets.list
  • Configurar o agente de serviço: resourcemanager.projects.setIamPolicy para conceder acesso de leitura Hosting (roles/storage.objectViewer) para que ele possa buscar o código enviado durante os builds.

Para a implantação inicial, o bucket do GCS é criado com um ciclo de vida de 30 dias, após o qual ele é excluído. No entanto, é possível gerenciar esse período no console do Cloud em Cloud Storage -> Buckets -> Ciclo de vida -> Regras. Consulte gerenciar ciclos de vida de objetos.

Permissões para implantações subsequentes (depois que o local é inicializado)

Depois que o bucket de origem e as vinculações de função são inicializados para um local (por uma implantação inicial da CLI ou configuração do console), desenvolvedores, editores ou administradores do App Hosting podem implantar atualizações. As permissões de administração para envolvidos no projeto não são necessárias para implantações rotineiras.

As permissões de implantação ativa incluem:

  • Verificar bucket: storage.buckets.list
  • Fazer upload do arquivo de origem: storage.objects.create
  • Acionar build e lançamento: permissões padrão do Hosting (apphosting.builds.create e apphosting.rollouts.create)

Implantar a partir da origem com a CLI Firebase

A CLI Firebase v14.4.0 e versões mais recentes permitem enviar o código-fonte e as configurações do app diretamente da máquina local para o Firebase. Isso é conveniente se você já gerencia outras implantações do Firebase (como regras de segurança ou funções) e quer implantar seu app da Web e serviços de back-end com um único comando da CLI.

Pré-requisitos

  • Seus projetos precisam estar no plano Blaze.
  • É preciso ter a versão 14.4.0 ou mais recente do firebase-tools.

Etapas da implantação

  1. Execute firebase init apphosting no diretório do projeto local.
  2. Quando solicitado, selecione Usar um projeto atual e escolha o Projeto do Firebase de destino.
  3. Selecione um back-end novo ou atual para fazer a implantação. Esta etapa configura as implantações Hosting para seu diretório local e solicita detalhes de configuração:
    • O ID do back-end em que a implantação será feita.
    • A região para implantação, se você estiver criando um back-end
    • O caminho para o diretório raiz do código do aplicativo
    • O ambiente de execução do Node.js de sua preferência. Ao selecionar um ambiente de execução com versão, você ativa as Atualizações automáticas de imagens de base (ABIU) para aplicar patches de segurança automaticamente ao seu ambiente subjacente.
  4. O App Hosting salva suas preferências de implantação em firebase.json, criando o arquivo no projeto local se ele ainda não existir. Quando a inicialização for concluída, execute firebase deploy para implantar seu código-fonte.

Exemplo de firebase.json

{
  "apphosting": [
    {
      "backendId": "my-backend",
      // rootDir specifies the directory containing the app to deploy, but the entire
      // parent directory of firebase.json will be zipped and uploaded to ensure that
      // dependencies outside of the app directory will be available at build time.
      "rootDir": "./my-app",
      "ignore": [
        "node_modules",
        ".git",
        "firebase-debug.log",
        "firebase-debug.*.log",
        "functions"
      ]
    }
  ]
}

Implantar com o console do Firebase (upload de ZIP)

O Firebase console oferece uma interface gráfica para implantar aplicativos fazendo upload direto de um arquivo de origem compactado. Isso serve como uma alternativa ao fluxo de conexão do GitHub para casos em que você prefere não usar o GitHub ou prefere uma configuração de CI/CD diferente.

Os uploads de arquivos podem ser feitos durante a criação inicial do back-end ou ao criar um lançamento manual em um back-end atual, incluindo aqueles implantados originalmente usando a CLI Firebase.

Formatos aceitos

O uploader do console valida e aceita nativamente dois formatos de arquivo compactado:

  • .zip
  • .tgz

Esses formatos são exibidos explicitamente no texto de descrição do carregador de arquivos.

Etapas da implantação

Opção A: durante a integração inicial do back-end
  1. Selecionar origem: no assistente de criação de back-end, selecione Fazer upload de um arquivo ZIP na etapa "Como você quer importar seu app?".
  2. Preparação para integração: clicar em "Próxima" aciona o fluxo de preparação em segundo plano, que ativa sequencialmente a API Storage, garante que as funções corretas estejam configuradas e faz o upsert do bucket. A interface mostra um spinner de carregamento com mensagens de status dinâmicas: "Ativando a API...", "Verificando permissões..." e "Preparando bucket...".
    • Tratamento de erros e proteções: se alguma etapa de preparação falhar (por exemplo, um usuário que não é proprietário receber um 403 PERMISSION_DENIED devido a permissões insuficientes do IAM), a interface vai mostrar um aviso dedicado instruindo você a entrar em contato com um proprietário do projeto. A navegação por etapas fica bloqueada, e o botão "Próxima" e a opção final "Concluir e implantar" permanecem desativados até que o problema seja resolvido.
  3. Fazer upload de arquivos: depois que a preparação for concluída, selecione ou arraste o arquivo de arquivamento para o componente de upload de arquivos.

  4. Configurar configurações: especifique o diretório raiz do app (o padrão é /).

  5. Clique em Concluir e implantar: o botão independente "Concluir" fica desativado para uploads de arquivos zip porque o envio de um arquivo é uma ação única e precisa ser seguida imediatamente por uma implantação para garantir um back-end funcional.

Opção B: criar um lançamento manual
  1. Abrir caixa de diálogo: no painel Hosting, clique em Criar lançamento.
  2. Selecionar origem: selecione Fazer upload de um ZIP no stepper da caixa de diálogo. Se o backend não tiver uma conexão do GitHub, a opção "GitHub" vai estar desativada.
  3. Preparação e upload: a seleção aciona o mesmo fluxo de preparação em segundo plano ("Ativando a API...", Verificando permissões... e Preparando bucket...). Depois de concluir, arraste ou selecione o arquivo de arquivo usando o carregador, especifique o Diretório raiz do app e clique em Implantar para acionar a criação e o lançamento.

Implantar com o Terraform

Se você precisar de mais controle sobre o processo de build e o ambiente implantado, use o Terraform. O Terraform permite definir e gerenciar seus recursos do App Hosting usando arquivos de configuração declarativos e oferece a capacidade de implantar sua própria imagem de contêiner pré-criada diretamente no App Hosting em vez de depender do App Hosting para criar com base no seu código fonte.

Se você não conhece o Terraform, consulte Começar a usar o Terraform e o Firebase. Se você já conhece o Terraform, comece com arquivos de configuração de exemplo e outros recursos do App Hosting.

Configurar uma conexão do GitHub para CI/CD

É possível conectar um repositório do GitHub a qualquer momento na guia Implantação das configurações de um back-end no console Firebase. Isso permite implantar um protótipo de app de um ambiente local e fazer a transição para um pipeline de CI/CD automatizado quando estiver tudo pronto.

Implantar usando ferramentas de IA

Vamos desativar o Firebase Studio em 22 de março de 2027. Embora seus back-ends do App Hosting não sejam afetados, o botão Publicar em Firebase Studio será desativado. Para continuar publicando atualizações sem mudar o URL, migre seu projeto. Saiba como migrar.