As of January 2022
Debugging
Setting up Firebase Datastore Emulator (FDE)
The Firebase Datastore Emulator (FDE) emulates the Google Datastore in App Engine. This is meant to run on Java 8 platforms. When correctly setup, any Datastore operations are done locally and stored to a file called local_db.bin.
The documentation for using the Firebase Datastore Emulator can be found at:
https://cloud.google.com/datastore/docs/tools/datastore-emulator
It should be noted that this documentaton contains errors and is missing some important settings. To use Firebase Datastore Emulator, install the emulator by running the following command from a terminal:
gcloud components install cloud-datastore-emulator
Start the emulator in a terminal:
gcloud beta emulators datastore start --data-dir=fbdatastore --host-port=localhost:8100
The official documentation does not indicate to use the --host-port flag. If you leave this flag out, a random port will be selected. But experience has shown that letting the port be randomly selected can result in exceptions generated by the client library used to access the local datastore - even when the port is correctly set in the environment variables.
The --data-dir flag indicates the directory where the local database file is stored. Here, it is specified as fbdatastore but you can use any folder located anywhere. You should make sure that the folder already exists before you start the emulator. In the example shown here, no path is included. This means that when you start the emulator, the directory specified by --data-dir should be in the same folder where you are launching the emulator.
The emulator will only create the local_db.bin file when you initially write data to it. If you don't write any data, it will not be created. Even it isn't created, the client APIs will still work correctly when reading from it, typically returning null values for any entities that you attempt to access. No exception will be thrown if the database file does not exist.
If the --data-dir is set to fbdatastore as used here, the local_db.bin file will be created under:
fbdatastore/WEB-INF/appengine-generated/local_db.bin
After the emulator has started, you can verify that it is running but opening a browser window and navigating to the url:
http://localhost:8100
This will only display the text "ok".
Before you can start debugging the app, several environment variables need to be set. You need to open a new terminal window and execute the following commands to set several variables:
export DATASTORE_DATASET=[project-id]
export DATASTORE_EMULATOR_HOST=localhost:8100
export DATASTORE_EMULATOR_HOST_PATH=localhost:8100/datastore
export DATASTORE_HOST=http://localhost:8100
export DATASTORE_PROJECT_ID=[project-id]
export DATASTORE_USE_PROJECT_ID_AS_APP_ID=true
The client libraries for the Datastore expect the app id to be used. But it was found that using only the app id didn't work. The environment variable DATASTORE_USE_PROJECT_ID_AS_APP_ID needs to be set as well. This is not specified in the documentation.
It should be noted that the official docs show the following:
export DATASTORE_DATASET=my-project-id
export DATASTORE_EMULATOR_HOST=::1:8432
export DATASTORE_EMULATOR_HOST_PATH=::1:8432/datastore
export DATASTORE_HOST=http://::1:8432
export DATASTORE_PROJECT_ID=my-project-id
For MacOS, this is wrong. The variables with values set to ::1 is wrong. Using this will cause exceptions and probably prevent the emulator from even loading. The ::1 needs to be replaced with localhost, as shown above.
You can just copy the 6 lines shown above and paste them into a terminal and hit Enter. But it is easier to just place these into a bash file and execute it. These need to be set before the local development server is started. The following bash file will set the environment variables and then start the development server:
export DATASTORE_DATASET=[project-id]
export DATASTORE_EMULATOR_HOST=localhost:8100
export DATASTORE_EMULATOR_HOST_PATH=localhost:8100/datastore
export DATASTORE_HOST=http://localhost:8100
export DATASTORE_PROJECT_ID=[project-id]
export DATASTORE_USE_PROJECT_ID_AS_APP_ID=true
java_dev_appserver.sh --address=0.0.0.0 --port=8080 --disable_update_check --jvm_flag=-Xdebug --jvm_flag=-Xrunjdwp:transport=dt_socket,server=y,suspend=n,address=8000 build/exploded-website
Replace [project-id] with the project id shown in your Googel Cloud Platform console (don't include the square brackets).
The address parameter for java_dev_appserver.sh is set here to 8000. You will need to set this in your IDE. Also, the port for java_dev_appserver.sh is set to 8080. You can set this to whatever works on your system and doesn't conflict with any existing ports used elsewhere. The last parameter for java_dev_appserver.sh is the location of your war files, which is the compiled app. Here, it is located at build/web-site. Replace this with the location of your own build files.
To view the datastore locally in your browser, navigate to:
http://localhost:8080/_ah/admin/datastore
Details on the command parameters used to start the emulator can be found at:
https://cloud.google.com/sdk/gcloud/reference/beta/emulators/datastore/start
