Configurar e gerenciar back-ends de hospedagem de apps

App Hosting foi projetado para ser fácil de usar e ter baixa manutenção, com configurações padrão otimizadas para a maioria dos casos de uso. Ao mesmo tempo, App Hosting oferece ferramentas para você gerenciar e configurar back-ends para suas necessidades específicas. Este guia descreve essas ferramentas e processos.

Definir e atualizar variáveis de ambiente

Às vezes, você pode precisar de mais configurações para o processo de build. App Hosting oferece configuração de ambiente para armazenar e recuperar esse tipo de dados para seu projeto pelo console Firebase e, como alternativa, em apphosting.yaml.

Definir variáveis de ambiente no console Firebase é a maneira mais rápida de começar. Use apphosting.yaml se precisar armazenar e acessar parâmetros de Secret, definir variáveis que só estão disponíveis no momento do build ou da execução ou compartilhar variáveis de ambiente em vários ambientes. Com o console e apphosting.<env>.yaml, é possível definir valores diferentes para ambientes diferentes.

Firebase console

Uma captura de tela da caixa de diálogo do console do Firebase para adicionar variáveis de ambiente

apphosting.yaml 

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app

Atualizar variáveis

É possível adicionar, editar ou excluir variáveis de ambiente no Firebase console ou usando apphosting.yaml:

  • Firebase console:

    1. No console do Firebase, acesse Hosting e sem servidor > App Hosting.

    2. Acesse Ver back-end > Configurações > Ambiente.

    3. Adicione, edite ou exclua variáveis de ambiente.

  • apphosting.yaml:

    Saiba como criar e editar o arquivo manualmente.

As mudanças só vão entrar em vigor no próximo lançamento e não vão afetar o atual. Salve e crie um novo lançamento ou salve as variáveis e implante mais tarde.

Definir a disponibilidade de variáveis

As variáveis de ambiente criadas no console Firebase estão disponíveis no tempo de build e no tempo de execução. Essa também é a condição padrão para variáveis definidas em apphosting.yaml, a menos que você tenha restringido esse escopo usando a propriedade availability. Em apphosting.yaml (mas não no console), é 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.

env:
-   variable: STORAGE_BUCKET
    value: mybucket.firebasestorage.app
    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.firebasestorage.app
    availability:
    -   BUILD
    -   RUNTIME

Arquivos dotenv para Next.js

Para apps Next.js, os arquivos dotenv que contêm variáveis de ambiente funcionam com o App Hosting.

Ao criar ou atualizar um back-end, é possível transferir variáveis de ambiente de seu dotenv arquivo para o console Firebase copiando e colando todo o conteúdo do arquivo dotenv no primeiro campo "Chave" do formulário "Adicionar novo" em Configurações de variáveis de ambiente.

Todas as variáveis de ambiente copiadas dessa forma precisam ser formatadas corretamente no formulário, sem a necessidade de inserir cada uma individualmente, desde que a entrada tenha um formato como este:

KEY1=value1
KEY2=value2
KEY3=value3

Para um controle complexo ou granular de variáveis de ambiente com qualquer framework, nós recomendamos o uso de apphosting.yaml.

Variáveis ​​de ambiente preenchidas automaticamente

Há variáveis de ambiente que são preenchidas automaticamente por App Hosting. Isso inclui as preenchidas pelo Google Cloud, bem como variáveis de ambiente específicas do Firebase quando appId é definido no back-end durante a configuração:

  • FIREBASE_CONFIG: (disponível nos ambientes de build e de execução) fornece as seguintes informações de configuração do projeto do Firebase:

    {
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
  "projectId": 'PROJECT_ID'
}

    Essa configuração é aplicada automaticamente quando você inicializa o Firebase SDK Admin sem argumentos.

  • FIREBASE_WEBAPP_CONFIG: (disponível apenas no ambiente de build) fornece as seguintes informações de configuração do projeto do Firebase:

    {
  "apiKey": 'API_KEY',
  "appId": 'APP_ID',
  "authDomain": 'AUTH_DOMAIN.firebaseapp.com',
  "databaseURL": 'https://DATABASE_NAME.firebaseio.com',
  "messagingSenderId": 'PROJECT_NUMBER',
  "projectId": 'PROJECT_ID',
  "storageBucket": 'PROJECT_ID.firebasestorage.app',
}

    O SDK do Firebase para JS verifica automaticamente essa FIREBASE_WEBAPP_CONFIG variável de ambiente em um script postinstall durante o build, permitindo que você também inicialize o SDK do cliente sem argumentos.

Consulte Inicializar automaticamente o SDK Admin do Firebase e os SDKs da Web para mais detalhes sobre como usar essas variáveis de ambiente para inicializar os SDKs.

Os valores na configuração real do Firebase vão corresponder aos recursos específicos provisionados no projeto.

Hierarquia de variáveis

O Firebase App Hosting aplica as variáveis em uma ordem de precedência com base na origem delas. Por exemplo, os valores definidos no console Firebase sempre substituem ou têm precedência sobre os valores definidos em apphosting.yaml e dotenv arquivos.

Confira a ordem de precedência completa:

  1. Firebase console → variáveis definidas no console
  2. apphosting.<env>.yaml → variáveis especificadas em um arquivo yaml específico do ambiente, como apphosting.staging.yaml (consulte Implantar vários ambientes)
  3. apphosting.yaml → variáveis especificadas no arquivo apphosting.yaml
  4. Sistema do Firebase → variáveis definidas pelo Firebase que contêm valores para firebase_config json ou firebase_webapp_config, bem como variáveis de ambiente que definem os nomes de host e as portas para apps SSR (definidos pelos adaptadores do App Hosting em bundle.yaml)

Nomes reservados e limitações

As variáveis de ambiente definidas no Cloud Run contrato de ambiente de execução do contêiner são reservadas e não podem ser definidas.

Variáveis de ambiente fornecidas pelo ambiente, além das definidas automaticamente, podem ser alteradas em futuras versões do ambiente de execução. Uma prática recomendada é não depender de ou modificar as variáveis de ambiente que você não tenha definido explicitamente e prefixar todas as variáveis de ambiente com uma chave exclusiva para evitar conflitos.

Algumas chaves de variáveis de ambiente são reservadas para uso interno. Não use nenhuma dessas chaves nos arquivos de configuração:

  • Strings vazias ("")
  • Chaves que contêm "="
  • Chaves que começam com X_FIREBASE_, X_GOOGLE_ ou CLOUD_RUN_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION
  • Chaves duplicadas

Criar e editar apphosting.yaml

Para configurações avançadas, como secrets ou configurações de ambiente 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 oferece suporte a referências a secrets gerenciados com o Secret Manager do Google Cloud, tornando-o seguro para fazer 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 configuração de exemplo (comentada). Após a edição, um arquivo apphosting.yaml típico pode ter esta aparência, com configurações para o serviço Cloud Run do back-end, algumas variáveis de ambiente e algumas referências a secrets gerenciados pelo Secret Manager do Google 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.firebasestorage.app
    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 fornece mais informações e contexto para essas configurações de exemplo.

Configurar as configurações do serviçoCloud Run

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

  • cpu: número de CPUs usadas para cada instância de exibiçã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: 100 e gerenciado por cota)
  • minInstances: número de contêineres a serem mantidos ativos (padrão: 0).
  • concurrency : número máximo de solicitações que cada instância de exibição pode receber (padrão: 80).

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

  • Mais de 4 GiB requer 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.

Substituir scripts de build e execução

App Hosting infere o comando de build e inicialização do app com base no framework detectado. Se você quiser usar um comando de build ou inicialização personalizado, substitua os padrões do App Hosting em apphosting.yaml.

scripts:
  buildCommand: next build --no-lint
  runCommand: node dist/index.js

A substituição do comando de build tem precedência sobre todos os outros comandos de build e desativa os adaptadores de framework do app e desativa todas as otimizações específicas do framework fornecidas por App Hosting. É melhor usar quando os recursos do app não são bem compatíveis com os adaptadores. Se você quiser mudar o comando de build , mas ainda usar os adaptadores fornecidos, defina o script de build em package.json , conforme descrito em App Hosting adaptadores de framework.

Use a substituição do comando de execução quando houver um comando específico que você queira usar para iniciar o app, que seja diferente do App Hosting-inferido.

Configurar a saída do build

App Hosting otimiza as implantações de apps por padrão, excluindo arquivos de saída não utilizados , conforme indicado pelo framework. Se você quiser otimizar ainda mais o tamanho da implantação do app ou ignorar as otimizações padrão, substitua isso em apphosting.yaml.

outputFiles:
  serverApp:
    include: [dist, server.js]

O parâmetro include recebe uma lista de diretórios e arquivos relativos ao diretório raiz do app que são necessários para implantar o app. Se você quiser garantir que todos os arquivos sejam mantidos, defina "include" como [.] e todos os arquivos serão implantados.

Armazenar e acessar parâmetros de secret

Informações sensíveis, como chaves de API, precisam ser armazenadas como secrets. É possível referenciar secrets em apphosting.yaml para evitar o check-in de informações sensíveis no controle de origem.

Os parâmetros do tipo secret representam parâmetros de string que têm um valor armazenado no Secret Manager do Google Cloud. Em vez de derivar o valor diretamente, os parâmetros de 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 Secret Manager do Google Cloud podem ter várias versões. Por padrão, o valor de um parâmetro de secret disponível para o 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 do ciclo de vida de parâmetros, poderá fixar versões específicas com o Secret Manager do Google Cloud. Por exemplo, para fixar na versão 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

É possível criar secrets com o Firebase comando da CLI firebase apphosting:secrets:set, e 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 de secret a apphosting.yaml.

Para usar o conjunto completo de funcionalidades do Secret Manager do Google Cloud, use o console do Secret Manager do Google Cloud. Se você fizer isso, será necessário conceder permissões ao back-end App Hosting com o comando da CLI Firebase firebase apphosting:secrets:grantaccess.

Configurar o acesso VPC

O back-end do App Hosting pode se conectar a uma rede de nuvem privada virtual (VPC). Para mais informações e um exemplo, consulte Conectar Firebase App Hosting a uma rede VPC.

Use o mapeamento vpcAccess no arquivo apphosting.yaml para configurar o acesso. Use um nome de rede/conector totalmente qualificado ou um ID. O uso de IDs permite a portabilidade entre ambientes de teste e produção com diferentes conectores/redes.

Configuração de saída de VPC direta (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: PRIVATE_RANGES_ONLY # Default value
    networkInterfaces:
      # Specify at least one of network and/or subnetwork
      - network: my-network-id
        subnetwork: my-subnetwork-id

Configuração do conector sem servidor (apphosting.yaml):

runConfig:
  vpcAccess:
    egress: ALL_TRAFFIC
    connector: connector-id

Gerenciar back-ends

Os comandos para gerenciamento básico de App Hosting back-ends são fornecidos no Firebase console e na Firebase CLI. Esta seção descreve algumas das tarefas de gerenciamento mais comuns, incluindo a criação e 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.

Firebase console: acesse Hosting e sem servidor > App Hosting, e clique em Criar back-end (se esse for o primeiro back-end no seu projeto do Firebase, clique em Começar).

Firebase CLI: (v13.15.4 ou mais recente) para criar um back-end, execute o seguinte comando na raiz do diretório do projeto local, fornecendo o ID do projeto como um argumento:

firebase apphosting:backends:create --project PROJECT_ID

Para o console ou a CLI, siga as instruções para escolher uma região, configurar uma conexão do GitHub, e configurar estas configurações básicas de implantação:

  • Defina o diretório raiz do app (o padrão é /)

    Geralmente, é onde o arquivo package.json está localizado.

  • Defina a ramificação ativa

    Esta é a ramificação do seu repositório do GitHub que é implantada no seu URL ativo. Geralmente, é a ramificação em que as ramificações de recursos ou de desenvolvimento são mescladas.

  • Aceite ou recuse lançamentos automáticos

    Os lançamentos automáticos são ativados por padrão. Após a conclusão da criação do back-end, é possível escolher que o app seja implantado no App Hosting imediatamente.

  • Atribua um nome ao back-end.

Excluir um back-end

Para remover totalmente um back-end, primeiro use o Firebase console ou a Firebase CLI para excluí-lo e, em seguida, remova manualmente os recursos relacionados, tomando cuidado para não excluir recursos que possam ser usados por outros back-ends ou outros aspectos do seu projeto do Firebase.

Firebase console: no menu Configuração, selecione Excluir back-end.

Firebase CLI: (v13.15.4 ou mais recente)

  1. Execute o comando a seguir para excluir o App Hosting back-end. Isso desativa todos os domínios do back-end e exclui o serviço associado Cloud Run:

    firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID

  2. (Opcional) Na guia do console do Google Cloud para Artifact Registry, exclua a imagem do back-end em "firebaseapphosting-images".

  3. No Secret Manager do Google Cloud, exclua todos os secrets com "apphosting" no nome do secret, tomando cuidado especial para garantir que esses secrets não sejam usados por outros back-ends ou outros aspectos do seu projeto do Firebase.