App Hosting has been designed for ease of use and low maintenance, with default settings optimized for most use cases. At the same time, App Hosting provides tools for you to manage and configure backends for your specific needs. This guide describes those tools and processes.
Configure a backend
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.
To create apphosting.yaml
, run the following command:
firebase init apphosting
This creates a basic starter apphosting.yaml
file with example (commented)
configuration. After editing, a typical apphosting.yaml
file might look like
the following, 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.
Configure 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.
Configure the build environment
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
Store and access 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:
- Implement a service worker that adds the right headers for your app on requests to server.
- Get the headers from the request on the server, and convert that to an auth
user with
FirebaseServerApp
.
Manage backends
Commands for basic management of App Hosting backends are provided in the Firebase CLI. Some operations are also available in the Firebase console. This section will describe some of the more common management tasks, including creating and deleting backends.
Create a backend
An App Hosting backend is the collection of managed resources that App Hosting creates to build and run your Web app. You can create and list App Hosting backends using the Firebase console or Firebase CLI.
Firebase console: From the Build menu, select App Hosting and then Get started.
CLI: (Version 13.15.4 or later) To create a backend, run the following command from the root of your local project directory, supplying your projectID and preferred region as arguments:
firebase apphosting:backends:create --project PROJECT_ID --location us-central1
For both console or CLI, follow the prompts to assign a name to your backend, to set up a GitHub connection, and configure these basic deployment settings:
Set your app's root directory (defaults to
/
)This is usually where your
package.json
file is located.
Set the live branch
This is the branch of your GitHub repository that gets deployed to your live URL. Often, it's the branch into which feature branches or development branches are merged.
Accept or decline automatic rollouts
Automatic rollouts are enabled by default. At completion of backend creation, you can choose for your app to be deployed to App Hosting immediately.
Delete a backend
To fully remove a backend, first use the Firebase CLI and then manually remove related assets, taking special care not to delete any resources that might be used by other backends or other aspects of your Firebase project.
Run the following command to delete the App Hosting Backend. This disables all domains for your backend and deletes the associated Cloud Run service:
firebase apphosting:backends:delete BACKEND_ID --project PROJECT_ID --location us-central1
(Optional) In the Google Cloud Console tab for Artifact Registry, delete the image for your backend in "firebaseapphosting-images".
In Cloud Secret Manager, delete any secrets with "apphosting" in the secret name, taking special care to make sure these secrets are not used by other backends or other aspects of your Firebase project.