Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

Esta página foi traduzida pela API Cloud Translation.

Configurar e gerenciar back-ends de hospedagem de apps

O App Hosting foi projetado para facilitar o uso e reduzir a manutenção, com configurações padrão otimizadas para a maioria dos casos de uso. Ao mesmo tempo, o App Hosting fornece ferramentas para gerenciar e configurar back-ends para suas necessidades específicas. Este guia descreve essas ferramentas e processos.

Configurar um back-end

Para configurações avançadas, como variáveis de ambiente ou configurações de execução, como simultaneidade, CPU e limites de memória, é necessário criar e editar o arquivo apphosting.yaml no diretório raiz do app. Esse arquivo também oferece suporte a referências a segredos gerenciados com o Cloud Secret Manager, tornando seguro o check-in no controle de origem.

Para criar apphosting.yaml, execute o seguinte comando:

firebase init apphosting

Isso cria um arquivo apphosting.yaml inicial básico com exemplo de configuração (comentado). Após a edição, um arquivo apphosting.yaml típico pode ficar assim, com configurações para o serviço Cloud Run do back-end, algumas variáveis de ambiente e algumas referências a segredos gerenciados pelo Gerenciador de secrets do Cloud:

# Settings for Cloud Run
runConfig:
  minInstances: 2
  maxInstances: 100
  concurrency: 100
  cpu: 2
  memoryMiB: 1024

# Environment variables and secrets
env:
  - variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
      - BUILD
      - RUNTIME

  - variable: API_KEY
    secret: myApiKeySecret

    # Same as API_KEY above but with a pinned version.
  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

    # Same as API_KEY above but with the long form secret reference as defined by Cloud Secret Manager.
  - variable: VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID

    # Same as API_KEY above but with the long form secret reference with pinned version.
  - variable: PINNED_VERBOSE_API_KEY
    secret: projects/test-project/secrets/secretID/versions/5

O restante deste guia oferece mais informações e contexto sobre esses exemplos de configurações.

Configurar as configurações do serviço Cloud Run

Com as configurações de apphosting.yaml, é possível definir como o serviço Cloud Run é provisionado. As configurações disponíveis para o serviço Cloud Run são fornecidas no objeto runConfig:

cpu: número de CPUs usadas para cada instância de veiculação (padrão: 0).
memoryMiB: quantidade de memória alocada para cada instância de exibição em MiB (padrão 512)
maxInstances: número máximo de contêineres a serem executados por vez (padrão de 100 e gerenciado por cota)
minInstances: número de contêineres que devem ser sempre mantidos ativos (padrão 0).
concurrency: número máximo de solicitações que cada instância de veiculação pode receber (padrão: 80).

Observe a relação importante entre cpu e memoryMiB. A memória pode ser definida para qualquer valor inteiro entre 128 e 32768, mas aumentar o limite de memória pode requerer o aumento dos limites da CPU:

Mais de 4 GiB exige pelo menos 2 CPUs
Mais de 8 GiB requer pelo menos 4 CPUs
Mais de 16 GiB requer pelo menos 6 CPUs
Mais de 24 GiB requer pelo menos 8 CPUs

Da mesma forma, o valor de cpu afeta as configurações de simultaneidade. Se você definir um valor menor que 1 CPU, será necessário definir a simultaneidade como 1, e a CPU só será alocada durante o processamento da solicitação.

Configurar o ambiente de build

Às vezes, você vai precisar de configuração adicional para o processo de build, como chaves de API de terceiros ou configurações ajustáveis. O App Hosting oferece configuração de ambiente em apphosting.yaml para armazenar e recuperar esse tipo de dados para seu projeto.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com

Para apps Next.js, os arquivos dotenv que contêm variáveis de ambiente também funcionam com App Hosting. Recomendamos o uso de apphosting.yaml para controle granular de variáveis de ambiente com qualquer framework.

No apphosting.yaml, é possível especificar quais processos têm acesso à sua variável de ambiente usando a propriedade availability. É possível restringir uma variável de ambiente para que ela esteja disponível apenas para o ambiente de build ou apenas para o ambiente de execução. Por padrão, ele está disponível para os dois.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

Para apps Next.js, também é possível usar o prefixo NEXT_PUBLIC_ da mesma forma que no arquivo dotenv para tornar uma variável acessível no navegador.

env:
-   variable: NEXT_PUBLIC_STORAGE_BUCKET
    value: mybucket.appspot.com
    availability:
    -   BUILD
    -   RUNTIME

As chaves de variável válidas são compostas de caracteres de A a Z ou sublinhados. Algumas chaves de variáveis de ambiente são reservadas para uso interno. Não use nenhuma dessas chaves nos arquivos de configuração:

Qualquer variável que comece com X_FIREBASE_
PORT
K_SERVICE
K_REVISION
K_CONFIGURATION

Armazenar e acessar parâmetros secretos

Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. É possível referenciar secrets no apphosting.yaml para evitar a verificação de informações confidenciais no controle de origem.

Os parâmetros do tipo secret representam parâmetros de string que têm um valor armazenado no Cloud Secret Manager. Em vez de derivar o valor diretamente, os parâmetros do secret verificam a existência no Secret Manager do Google Cloud e carregam os valores durante o lançamento.

  -   variable: API_KEY
      secret: myApiKeySecret

Os secrets no Cloud Secret Manager podem ter várias versões. Por padrão, o valor de um parâmetro secreto disponível para seu back-end ativo é fixado na versão mais recente disponível do secret no momento em que o back-end foi criado. Se você tiver requisitos de controle de versões e gerenciamento de ciclo de vida de parâmetros, poderá fixar versões específicas com o Cloud Secret Manager. Por exemplo, para fixar na versão 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

É possível criar secrets com o comando firebase apphosting:secrets:set da CLI. Você vai receber uma solicitação para adicionar as permissões necessárias. Esse fluxo oferece a opção de adicionar automaticamente a referência secreta a apphosting.yaml.

Para usar o pacote completo de funcionalidades do Cloud Secret Manager, use o console do Cloud Secret Manager. Se você fizer isso, vai precisar conceder permissões ao back-end App Hosting com o comando firebase apphosting:secrets:grantaccess da CLI.

Sincronizar o estado do Firebase Auth

Os apps que usam o Firebase Auth precisam considerar o uso do SDK da Web do Firebase para manter o estado de autenticação sincronizado entre o cliente e o servidor. Isso pode ser facilitado implementando FirebaseServerApp com um service worker. O fluxo de tarefas básico é:

Implemente um worker de serviço que adicione os cabeçalhos corretos para o app em solicitações ao servidor.
Receba os cabeçalhos da solicitação no servidor e converta-os em um usuário de autenticação com FirebaseServerApp.

Gerenciar back-ends

Os comandos para gerenciamento básico de back-ends App Hosting são fornecidos na CLI Firebase. Algumas operações também estão disponíveis no console Firebase. Esta seção descreve algumas das tarefas de gerenciamento mais comuns, incluindo a criação e a exclusão de back-ends.

Criar um back-end

Um back-end App Hosting é a coleção de recursos gerenciados que App Hosting cria para criar e executar seu app da Web. É possível criar e listar back-ends de App Hosting usando o console do Firebase ou a CLI Firebase.

Console do Firebase: no menu Build, selecione App Hosting e, em seguida, Começar.

CLI: (versão 13.15.4 ou mais recente) para criar um back-end, execute o seguinte comando na raiz do diretório do projeto local, fornecendo o projectID e a região preferida como argumentos:

firebase apphosting:backends:create --project PROJECT_ID --location us-central1

No console ou na CLI, siga as instruções para atribuir um nome ao back-end, configurar uma conexão do GitHub e definir estas configurações básicas de implantação:

Defina o diretório raiz do seu app (padrão: /)

É onde o arquivo package.json geralmente está localizado.

Definir a ramificação ativa

Essa é a ramificação do repositório do GitHub que é implantada no URL ativo. Muitas vezes, é a ramificação em que as ramificações de recursos ou de desenvolvimento são mescladas.
Aceitar ou recusar lançamentos automáticos

As implantações automáticas são ativadas por padrão. Após a conclusão da criação do back-end, é possível escolher se o app será implantado no App Hosting imediatamente.

Excluir um back-end

Para remover totalmente um back-end, primeiro use a CLI Firebase e, em seguida, remova manualmente os recursos relacionados, tomando cuidado especial para não excluir nenhum recurso que possa ser usado por outros back-ends ou outros aspectos do seu projeto do Firebase.

Execute o comando a seguir para excluir o back-end App Hosting. Isso desativa todos os domínios do back-end e exclui o serviço Cloud Run associado:
```
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1
```
(Opcional) Na guia do Console do Google Cloud para Artifact Registry, exclua a imagem do back-end em "firebaseapphosting-images".
No Cloud Secret Manager, exclua todos os secrets com "apphosting" no nome do secret, com cuidado especial para garantir que eles não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.