Google Cloud Services - Firebase Dev Services

This extension implements DevServices for applications developed on with the Google Firebase platform. The DevService runs the appropriate emulators of the Firebase platform based on your configuration.

Be sure to have read the Google Cloud Services extension pack global documentation before this one, it contains general configuration and information.

Current status

The following emulators have been verified to work:

  • Firebase Auth

  • Firebase Firestore

  • Firebase Emulator UI

  • Realtime Database

  • PubSub

  • Cloud Storage

  • Firebase Hosting

  • Functions

The following emulators are currently not supported: * EventArc

Currently you can specify a custom firebase.json file but suport for this is limited. A future version will support reading the configuration from the firebase.json file instead of from the Quarkus configuration.

Bootstrapping the project

First, we need a new project. Create a new project with the following command (replace the version placeholder with the correct one):

mvn io.quarkus:quarkus-maven-plugin:${quarkusVersion}:create \
    -DprojectGroupId=org.acme \
    -DprojectArtifactId=firebase-admin-quickstart \
    -Dextensions="quarkus-google-cloud-firebase-devservices"
cd firebase-admin-quickstart

This command generates a Maven project, importing the Google Cloud Firebase extension.

If you already have your Quarkus project configured, you can add the quarkus-google-cloud-firebase extension to your project by running the following command in your project base directory:

./mvnw quarkus:add-extension -Dextensions="quarkus-google-cloud-firebase"

This will add the following to your pom.xml:

<dependency>
    <groupId>io.quarkiverse.googlecloudservices</groupId>
    <artifactId>quarkus-google-cloud-firebase</artifactId>
</dependency>

If you already have a firebase project (which you can create using the firebase tools by running firebase init), you need to make the following changes to get going: * Add "host" : "0.0.0.0" to all emulator entries * Add the hub, logging and UI emulators to the emulators configuration

{

  "emulators" : {
    "ui": {
      "port": 4000,
      "enabled": true,
      "host": "0.0.0.0"
    },
    "hub": {
      "port": 4400,
      "host": "0.0.0.0"
    },
    "logging": {
      "port": 4500,
      "host": "0.0.0.0"
    }
  }
}

  • If you use Firestore, also set the Firestore Websocket port

{
  "emulators" : {
    "firestore": {
      "port": 8080,
      "websocketPort" : 9150,
      "host": "0.0.0.0"
    }
  }
}

  • For both entries, you can of course use your own custom ports, where needed.

The extension will try to read the firebase.json file from the current working directory the process was started in (it will not attempt to traverse the directory upwards to try to find the file). In some cases you may need to specify this working directory. E.g. when using Gradle:

quarkusDev {
    workingDirectory = rootProject.projectDir
}

Custom Docker image

To run the emulators, a custom Docker image is build on the fly to run the Firebase emulators. This image is based on a NodeJS based image (refer to the configuration of the default value of quarkus.google.cloud.firebase.devservice.image-name to see the base image).

You can configure a custom image if needed as base image to run the Firebase Emulators in. This image has the following requirements:

  • The image must support NodeJS in a version compatible with the required Firebase Tools

  • The image must be alpine based (or at least able to install the following packages using apk: )

    • openjdk17-jre

    • bash

    • curl

    • openssl

    • gettext

    • nano

    • nginx

    • sudo

Custom Firebase JSON

If emulators are configured via the configuration options, a firebase.json file is generated inside the image to configure the various emulators. You can configure the Dev Services to use your own custom firebase.json file (e.g generated using the Firebase tools CLI). The following requirements are defined for this file:

  • Each of the emulators must be exposed on 0.0.0.0 as host as described here. If this is not done, the Emulators will not be reachable from the Docker host.

  • Emulators need to be configured to use the default ports. Customizing the ports on which they run is currently not supported (this might change in a future version).

Interaction with other extensions

The following extensions support Dev Services which conflicts with the Dev Services exposed by the Firebase Emulators.

  • Firestore

  • PubSub

  • TODO: Verify Storage

When including this module, these Dev Services will automatically be disabled, as the Firebase emulator should feature wise be on-par or more extensive than the individual emulators.

Configuration Reference

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

quarkus.google.cloud.project-id

Google Cloud project ID. The project is required to be set if you use the Firebase Auth Dev service.

Environment variable: QUARKUS_GOOGLE_CLOUD_PROJECT_ID

string

quarkus.google.cloud.devservices.firebase.prefer-firebase-dev-services

Indicates to use the dev service for Firebase. The default value is true. This indicator is used to detect the Firebase DevService and disable the DevServices for extensions which conflict with the Firebase DevService.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_PREFER_FIREBASE_DEV_SERVICES

boolean

true

quarkus.google.cloud.devservices.firebase.emulator.firebase-version

The version of the firebase tools to use. Default is to use the latest available version.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_FIREBASE_VERSION

string

latest

quarkus.google.cloud.devservices.firebase.emulator.docker.image-name

Sets the Docker image name for the Google Cloud SDK. This image is used to emulate the Pub/Sub service in the development environment. The default value is 'node:23-alpine'.

See also the documentation on Custom Docker images for more info about this image.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_IMAGE_NAME

string

node:20-alpine

quarkus.google.cloud.devservices.firebase.emulator.docker.docker-user

Id of the docker user to run the firebase executable. This is needed in environments where Docker does not perform a mapping to the user running Docker. In a Docker Desktop setup, Docker automatically performs this mapping and the data written by the emulator can be read by the user running the build. This is not the case in a regular (non-Desktop) setup, so you may need to set the user id and docker-group(). This option is often needed in CI environments.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_DOCKER_USER

int

quarkus.google.cloud.devservices.firebase.emulator.docker.docker-group

Id of the group to which the docker-user() belongs.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_DOCKER_GROUP

int

quarkus.google.cloud.devservices.firebase.emulator.docker.docker-user-env

Try to read the docker-user() from an environment variable

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_DOCKER_USER_ENV

string

quarkus.google.cloud.devservices.firebase.emulator.docker.docker-group-env

Try to read the docker-group() from an environment variable

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_DOCKER_GROUP_ENV

string

quarkus.google.cloud.devservices.firebase.emulator.docker.follow-std-out

Pipe Stdout of the container to the Quarkus logging

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_FOLLOW_STD_OUT

boolean

quarkus.google.cloud.devservices.firebase.emulator.docker.follow-std-err

Pipe Stedd of the container to the Quarkus logging

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_DOCKER_FOLLOW_STD_ERR

boolean

quarkus.google.cloud.devservices.firebase.emulator.cli.token

The token to use for firebase authentication. Run firebase login:ci locally to get a new token. This option is mandatory if you use firebase hosting.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CLI_TOKEN

string

quarkus.google.cloud.devservices.firebase.emulator.cli.java-tool-options

Sets the JAVA tool options for emulators based on the Java runtime environment like -Xmx. See also here

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CLI_JAVA_TOOL_OPTIONS

string

quarkus.google.cloud.devservices.firebase.emulator.cli.emulator-data

Allow to import and export data. Specify a path relative to the current working directory of the executable (for most unit tests, this is the root of the build directory) to be used for import and export of emulator data. The data will be written to a subdirectory called "emulator-data" of this directory. See also here

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CLI_EMULATOR_DATA

string

quarkus.google.cloud.devservices.firebase.emulator.cli.import-export

Indicate whether to import, export or both the data specified in emulator-data()

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CLI_IMPORT_EXPORT

import-only, export-only, import-export

quarkus.google.cloud.devservices.firebase.emulator.cli.debug

Enable firebase emulators debugging.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CLI_DEBUG

boolean

quarkus.google.cloud.devservices.firebase.emulator.custom-firebase-json

Indicate to use a custom firebase.json file instead of the automatically generated one. The custom firebase.json file MUST include a setting of

"host" : "0.0.0.0"

to ensure the ports of the emulator are exposed correctly at the docker container level.

See the section on Custom Firebase Json in the docs for more info.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_CUSTOM_FIREBASE_JSON

string

quarkus.google.cloud.devservices.firebase.emulator.ui.enabled

Indicates whether the service should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_UI_ENABLED

boolean

true

quarkus.google.cloud.devservices.firebase.emulator.ui.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_UI_EMULATOR_PORT

int

quarkus.google.cloud.devservices.firebase.emulator.ui.logging-port

Port on which to expose the logging endpoint port. This is needed in case you want to view the logging via the Emulator UI.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_UI_LOGGING_PORT

int

quarkus.google.cloud.devservices.firebase.emulator.ui.hub-port

Port on which to expose the hub endpoint port. This is needed if you want to use the hub API of the Emulator UI.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_EMULATOR_UI_HUB_PORT

int

quarkus.google.cloud.devservices.firebase.auth.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_AUTH_ENABLED

boolean

false

quarkus.google.cloud.devservices.firebase.auth.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_AUTH_EMULATOR_PORT

int

quarkus.google.cloud.devservices.firebase.hosting.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_HOSTING_ENABLED

boolean

false

quarkus.google.cloud.devservices.firebase.hosting.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_HOSTING_EMULATOR_PORT

int

quarkus.google.cloud.devservices.firebase.hosting.hosting-path

Path to the hosting files.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_HOSTING_HOSTING_PATH

string

quarkus.google.cloud.devservices.firebase.database.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_DATABASE_ENABLED

boolean

false

quarkus.google.cloud.devservices.firebase.database.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_DATABASE_EMULATOR_PORT

int

quarkus.google.cloud.devservices.firebase.firestore.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_FIRESTORE_ENABLED

boolean

false

quarkus.google.cloud.devservices.firebase.firestore.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_FIRESTORE_EMULATOR_PORT

int

quarkus.google.cloud.devservices.firebase.firestore.websocket-port

Port on which to expose the websocket port. This is needed in case the Firestore Emulator UI needs is used.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_FIRESTORE_WEBSOCKET_PORT

int

quarkus.google.cloud.devservices.firebase.firestore.rules-file

Path to the firestore.rules file.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_FIRESTORE_RULES_FILE

string

quarkus.google.cloud.devservices.firebase.firestore.indexes-file

Path to the firestore.indexes.json file.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FIREBASE_FIRESTORE_INDEXES_FILE

string

quarkus.google.cloud.devservices.functions.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FUNCTIONS_ENABLED

boolean

false

quarkus.google.cloud.devservices.functions.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_FUNCTIONS_EMULATOR_PORT

int

quarkus.google.cloud.devservices.pubsub.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_PUBSUB_ENABLED

boolean

false

quarkus.google.cloud.devservices.pubsub.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_PUBSUB_EMULATOR_PORT

int

quarkus.google.cloud.devservices.storage.enabled

Indicates whether the DevService should be enabled or not. The default value is 'false'.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_STORAGE_ENABLED

boolean

false

quarkus.google.cloud.devservices.storage.emulator-port

Specifies the emulatorPort on which the service should run in the development environment. The default is to expose the service on a random port.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_STORAGE_EMULATOR_PORT

int

quarkus.google.cloud.devservices.storage.rules-file

Path to the storage.rules file.

Environment variable: QUARKUS_GOOGLE_CLOUD_DEVSERVICES_STORAGE_RULES_FILE

string