Configure App Hosting

For advanced configuration such as environment variables or runtime settings such as concurrency, CPU, and memory limits, you'll need to create and edit the apphosting.yaml file in your app's root directory. This file also supports references to secrets managed with Cloud Secret Manager, making it safe to check into source control.

Here's what a typical apphosting.yaml file might look like, with settings for the backend's Cloud Run service, some environment variables, and some references to secrets managed by Cloud Secret Manager:

# 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

The rest of this guide provides more information and context for these example settings.

Cloud Run service settings

With apphosting.yaml settings, you can configure how your Cloud Run service is provisioned. The available settings for the Cloud Run service are provided in the runConfig object:

  • cpu – Number of CPUs used for each serving instance (default 0).
  • memoryMiB – Amount of memory allocated for each serving instance in MiB (default 512)
  • maxInstances – Maximum number of containers to ever run at a time (default of 100 and managed by quota)
  • minInstances – Number of containers to always keep alive (default 0).
  • concurrency – Maximum number of requests that each serving instance can receive (default 80).

Note the important relationship between cpu and memoryMiB; memory can be set to any integer value between 128 to 32768, but increasing the memory limit may require increasing CPU limits:

  • Over 4GiB requires at least 2 CPUs
  • Over 8GiB requires at least 4 CPUs
  • Over 16GiB requires at least 6 CPUs
  • Over 24GiB requires at least 8 CPUs

Similarly, the value of cpu affects concurrency settings. If you set a value less than 1 CPU, you must set concurrency to 1, and CPU will only be allocated during request processing.

Environment variables

Sometimes you'll need additional configuration for your build process, such as third-party API keys or tuneable settings. App Hosting offers environment configuration in apphosting.yaml to store and retrieve this type of data for your project.

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

For Next.js apps, dotenv files containing environment variables will also work with App Hosting. We recommend using apphosting.yaml for granular environment variable control with any framework.

In apphosting.yaml, you can specify which processes have access to your environment variable by using the availability property. You can restrict an environment variable to be available to only the build environment or available only to the runtime environment. By default, it's available to both.

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

For Next.js apps, you can also use the NEXT_PUBLIC_ prefix the same way you would in your dotenv file to make a variable accessible in the browser.

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

Valid variable keys are comprised of A-Z characters or underscores. Some environment variable keys are reserved for internal use. Don't use any of these keys in your configuration files:

  • Any variable beginning with X_FIREBASE_
  • PORT
  • K_SERVICE
  • K_REVISION
  • K_CONFIGURATION

Secret parameters

Sensitive information such as API keys should be stored as secrets. You can reference secrets in apphosting.yaml to avoid checking sensitive information into source control.

Parameters of type secret represent string parameters which have a value stored in Cloud Secret Manager. Instead of deriving the value directly, secret parameters check against existence in Cloud Secret Manager, and load the values during rollout.

  -   variable: API_KEY
      secret: myApiKeySecret

Secrets in Cloud Secret manager can have multiple versions. By default, the value of a secret parameter available to your live backend is pinned to the latest available version of the secret at the time the backend was built. If you have requirements for versioning and lifecycle management of parameters, you can pin to specific versions with Cloud Secret Manager. For example, to pin to version 5:

  - variable: PINNED_API_KEY
    secret: myApiKeySecret@5

You can create secrets with the CLI command firebase apphosting:secrets:set, and you will be prompted to add necessary permissions. This flow gives you the option to automatically add the secret reference to apphosting.yaml.

To use the full suite of Cloud Secret Manager functionality, you can instead use the Cloud Secret Manager console. If you do this, you'll need to grant permissions to your App Hosting backend with the CLI command firebase apphosting:secrets:grantaccess.

Synchronize Firebase Auth state

Apps using Firebase Auth should consider using the Firebase Web SDK to help keep authentication state synchronized between client and server. This can be facilitated by implementing FirebaseServerApp with a service worker. The basic task flow is:

  1. Implement a service worker that adds the right headers for your app on requests to server.
  2. Get the headers from the request on the server, and convert that to an auth user with FirebaseServerApp.