Install, configure and integrate Local Emulator Suite

The Firebase Local Emulator Suite can be installed and configured for different prototype and test environments, anything from one-off prototyping sessions to production-scale continuous integration workflows.

Install the Local Emulator Suite

For recommended installations using npm/nvm, Node.js version 8.0 or higher is required. For all installation types, Java version 1.8 or higher is required.

To install the Emulator Suite:

1. Install the Firebase CLI.

         $ npm install -g firebase-tools
       

2. If you haven't already done so, initialize the current working directory as a Firebase project, following the onscreen prompts to specify which products to use (Cloud Firestore, Realtime Database, Cloud Functions for Firebase, and/or Firebase Hosting), associate the directory with a registered Firebase project, and select programming language and other options, as needed.

         $ firebase init
       

3. Install emulators in one of two ways:
   • Preferred. Execute the command firebase init emulators. This command starts a configuration wizard that lets you select emulators of interest, download the corresponding emulator JAR files, and set emulator ports if the defaults are not appropriate.
   • Execute the command firebase emulators:start. If the firebase.json file created during project initialization identifies this as a project using Cloud Firestore or Realtime Database, the Firebase CLI automatically downloads and installs emulator JAR files for those products the first time they are invoked.

Once an emulator is installed, no update checks are performed and no additional automatic downloads will occur until you update your Firebase CLI version.

Alternative Firebase CLI installation method

If Node.js and its associated package management tools are not a good fit for your development environment, an alternative Firebase CLI installation method requiring only a bash shell and curl is available.

Note: This method will invoke sudo to complete the installation. If running non-interactively, for example in a continuous integration environment, please make sure password-less sudo is set up.

For Linux or MacOS, issue the following command. Complete instructions, covering Windows installations as well, are provided in Firebase CLI.

curl -sL firebase.tools | bash

Configure Emulator Suite

You can optionally configure the emulators' network ports and path to Security Rules definitions in the firebase.json file

If you don't configure these settings, the emulators will listen on their default ports, and the Cloud Firestore and Realtime Database emulators will run with open data security.

Change emulator ports by running firebase init emulators or by editing firebase.json manually. Change the path to Security Rules definitions by editing firebase.json manually.

Command	Description
init emulators	Start an emulator initialization wizard. Identify emulators to be installed and optionally specify emulator port settings. init emulators is non-destructive; accepting defaults will preserve the current emulator configuration.

Port configuration

Each emulator binds to a different port on your machine with a preferred default value.

Emulator	Default Port
Cloud Functions	5001
Realtime Database	9000
Cloud Firestore	8080
Cloud Pub/Sub	8085
Firebase Hosting	5000

Security Rules configuration

The emulators will take Security Rules configuration from the database and firestore configuration keys in firebase.json.

{
  // Existing firebase configuration ...
  "database": {
    "rules": "database.rules.json"
  },
  "firestore" {
    "rules": "firestore.rules"
  },

  // ...

  // Optional emulator configuration. Default
  // values are used if absent.
  "emulators": {
    "firestore": {
      "port": "8080"
    },
    "functions": {
      "port": "5001"
    },
    "database": {
      "port": "9000"
    },
    "pubsub": {
      "port": "8085"
    }

  }
}

Start up emulators

You can start emulators to run until manually terminated, or to run for the duration of a designated test script then automatically shut down.

Command	Description
emulators:start	Start emulators for the Firebase products configured in firebase.json. Emulator processes will continue running until explicitly stopped. Calling emulators:start will download the emulators to ~/.cache/firebase/emulators/ if they are not already installed. Use the optional --only flag to limit which emulators start. Supply a comma-separated list of emulator names, specifying one or more of 'firestore', 'database', 'functions' or 'hosting'.
emulators:exec scriptpath	Run the script at scriptpath after starting emulators for the Firebase products configured in firebase.json. Emulator processes will automatically stop when the script has finished running. Use the optional --only flag to limit which emulators start. Supply a comma-separated list of emulator names, specifying one or more of 'firestore', 'database', 'functions' or 'hosting'.

The firebase emulators:exec method is generally more appropriate for continuous integration workflows.

Integrate with your CI system

Running containerized Emulator Suite images

Installation and configuration of the Emulator Suite with containers in a typical CI setup is straightforward.

There are a few issues to note:

• JAR files are installed and cached at ~/.cache/firebase/emulators/.

  • You may want to add this path to your CI cache configuration to avoid repeated downloads.

• Emulator Suite requires Internet access.

  • Although the emulators don't send traffic to production Firebase services, they need Internet access to authenticate and to download dependencies.

• If you do not have a firebase.json file in your repository, you must add a command line argument to the emulators:start or emulators:exec command to specify which emulators should be started. For example,
  --only functions,firestore.

Generate an auth token (Hosting emulator only)

If your continuous integration workflows rely on Firebase Hosting, then you will need to login using a token in order to run firebase emulators:exec. The other emulators do not require login.

Note: If you have configured hosting in firebase.json but do not need it in CI test setups, use the --only flag to emulators:start or emulators:exec to include only the emulators that you need.

To generate a token, run firebase login:ci on your local environment; this should not be performed from a CI system. Follow instructions to authenticate. You should only need to perform this step once per project, since the token will be valid across builds. The token should be treated like a password; make sure it is kept secret.

If your CI environment allows you to specify environment variables that can be used in the build scripts, simply create an environment variable called FIREBASE_TOKEN, with the value being the access token string. The Firebase CLI will automatically pick up the FIREBASE_TOKEN environment variable and the emulators will start properly.

As a last resort, you can simply include the token in your build script, but make sure that untrusted parties do not have access. For this hard-coded approach, you can add --token "YOUR_TOKEN_STRING_HERE" to the firebase emulators:exec command.