Build and Deploy Ground from Source

The Ground platform consists of a web app and an Android mobile app, both of which use Firebase as a common backend. In order to use Ground, you must build and deploy an instance of Ground using the source files hosted on GitHub. This only needs to be done once per organization owning the Ground data; once deployed, Ground can host multiple surveys, each with their own permissions and sharing rules.

Note: For more information about Ground, see the Github repos: ground-platform and ground-android.

Setup overview

In order to set up and install Ground you need to complete the following steps:

  1. Create and configure a Firebase survey
  2. Configure and build the web app
  3. Configure and build the Android app
  4. Share Ground web login details and distribute the Android app

Prerequisites

Before you get started, you’ll need the following:

1. Create and configure a Firebase survey

The Firebase survey includes the configuration for your instance of Ground, as well as a Cloud Firestore database, Cloud Functions, Authentication, Cloud Storage, and Crashlytics. Firebase surveys are technically also Google Cloud surveys. However, we recommend creating a new Firebase survey for your Ground instance, rather than using an existing Cloud survey.

  1. Go to https://console.firebase.google.com/ and log into your Firebase account.
  2. Click Create a survey.
  3. Enter a survey name, accept the terms, and click Continue.
  4. Make sure that Enable Google Analytics for this survey is selected and click Continue. Ground does not currently use Google Analytics, but it may be useful in future versions.
  5. Create or select an Analytics account, accept the terms, and click Create survey.

Create a Firestore database

Cloud Firestore is used for storing Ground data, which is organized into a hierarchy of collections and documents. To learn how Ground data is represented in Cloud Firestore, see Cloud Firestore Representation page in the Ground platform wiki.

  1. From the left nav on the Firebase survey page, select Build > Firestore Database.
  2. Click Create database.
  3. Select Start in production mode and click Next.
  4. Select a Cloud Firestore location. For more information about selecting a location, see Location considerations.
  5. Click Enable.

Enable Google sign-in

Ground relies on Firebase for its Sign in with Google functionality.

  1. From the left nav on the Firebase survey page, select Build > Authentication.
  2. Click Get started.
  3. In the Sign-in providers list, select Google.
  4. Click the Enable toggle switch.
  5. Enter a public-facing login name, which will appear on the sign-in dialog.
  6. Select an email address for sign-in-related issues.
  7. Click Save.

Add another survey owner (optional)

If you’d like to allow someone else to be able to administer and modify the Firebase survey, you can grant them “owner” access as follows:

  1. From the left nav on the Firebase survey page, click the settings gear next to Survey Overview and select Users and permissions.
  2. Click Add member.
  3. Enter the email address of the person you would like to add as a survey owner.
  4. From the Role(s) list, select Owner.
  5. Click Add member.

Note: This step has no effect on who can view which Ground surveys in the web and Android app. Firebase permissions only control who can administer the backend via the command-line and Firebase console.

Grant users access by creating a passlist

Ground uses a passlist to control which users can sign into Ground surveys hosted in your new Firebase survey. This passlist is a collection of documents within the survey’s Firestore database where the IDs of the documents are the email addresses of the users in the passlist.

  1. From the left nav on the Firebase survey page, select Build > Firestore Database.
  2. Click Start collection.
  3. For the Collection ID, enter passlist, and click Next.
  4. Add the first user to the collection by entering the user’s email address as the Document ID. Add at least one field-value pair of your choosing and click Save. Typical values might include “addedBy”, “reason”, “org”, etc.

Note: If you would like to add all email addresses for a specified domain to the passlist, you can add a document that uses a regular expression to grant access to all email addresses matching a pattern. To do this, create a document in the passlist collection with the ID regexp containing a single field, also regexp, the value of which contains a regular expression matching email address of users allowed to create and/or access Ground surveys. For example, to add all users for the @example.com domain, you would enter .*@example[.]com as the regexp in the regexp document.

Enable the Resize Images Extension

  1. From the left nav on the Firebase survey page, click Extensions.
  2. Under Resize Images, click Install.
  3. Click Next.
  4. Click Next.
  5. Click Next.
  6. In the Configure extension section, specify the following values:
    • Size of reduced images: 200x200
    • Deletion of original file: No
    • Paths that contain images you want to resize (Optional): /user-media
    • Convert image to preferred types: original
  7. Click Install extension.

Change the survey billing plan to Blaze

By default, Firebase surveys use the free Spark plan. However, Ground requires functionality, such as Cloud Functions, which are not included in the Spark plan, so you need to change your billing plan to the pay-as-you-go Blaze plan.

  1. From the left nav on the Firebase survey page, click the settings gear next to Survey Overview and select Usage and billing.
  2. Click Details & settings.
  3. Click Modify plan.
  4. Under Blaze Pay as you go, click Select plan.
  5. Click Purchase.
  6. Optional: If you want to be notified when your usage meets certain thresholds:
    1. Click Set a budget alert.
    2. Enter an amount for the alert and click Set budget alert.

Note: For more information on Firebase pricing, see https://firebase.google.com/pricing.

Add the Android app to your Firebase survey

In order for the Ground Android app to access Firebase services, you must first add it to your Firebase survey. In a later step you will use the resulting keys to build the app binary from source.

  1. From the left nav on the Firebase survey page, click Survey Overview.
  2. Under Get started by adding Firebase to your app, click the Android icon.
  3. Under Register app, enter the following values:
    1. Android package name: com.google.android.gnd
    2. App nickname: Enter any nickname you want
    3. Debug signing certificate SHA-1: Leave blank
  4. Click Register app.
  5. Click Download google-services.json and save the file to add later to your Android Studio survey.
  6. Click Next.
  7. Click Next.
  8. Click Continue to console.

Add the web app to your Firebase survey

Similar to the configuration for the Android app described in the previous section, you must also add the Ground web app to your Firebase survey.

  1. From the left nav on the Firebase survey page, click Survey Overview.
  2. Under Get started by adding Firebase to your app, click the web icon.

    Note: If you do not see the app icons, click Add app, then click the web icon.

  3. In the App nickname field, enter any nickname you want to use for the web app.
  4. Check the Also set up Firebase Hosting for this app box.
  5. Click Register app.
  6. Click Next.
  7. Click Next.
  8. Click Continue to console.
  9. From the left nav on the Firebase survey page, click the settings gear next to Survey Overview and select Survey settings.
  10. In the Your apps section, scroll down to the web app you created.
  11. In the SDK setup and configuration section, select Config.
  12. Copy the code snippet and save it to a text file to add later to your web app configuration.

Enable the Google Maps APIs for your Firebase survey

Both the Android and web apps for Ground use the Google Maps API, so you need to enable the Maps SDK for your survey and retrieve the API keys to use with your apps.

  1. Go to the Google Cloud Console at http://console.cloud.google.com.
  2. If the selected survey is not the survey you created in Firebase for Ground, click survey name in the top menu bar and select your Ground survey.
  3. From the left nav, select APIs & Services > Library.
  4. Select Maps SDK for Android.
  5. Click Enable.
  6. From the left nav, select APIs.
  7. In the Additional APIs section, select Maps JavaScript API.
  8. Click Enable.
  9. From the left nav, select Credentials.
  10. In the API Keys section, copy the keys for Android key (auto created by Firebase) and Browser key (auto created by Firebase) and save them to a text file to add later to your Ground app.

2. Configure and build the web app

Once you have your Firebase survey configured, you’re ready to build and deploy the Ground web app. Like the Android app, the source files for the web app are stored on GitHub.

  1. In a terminal window, in the directory where you want to download the web app source code, run git clone https://github.com/google/ground-platform.git
  2. Within the cloned ground-platform directory, create a new file for the Maps API configuration: ground-platform/web-ng/src/environments/.google-maps-config.ts
  3. Add the following code to the file:

     export const googleMapsConfig = {
     apiKey: 'YOUR_API_KEY',
     };
    
  4. Replace 'YOUR_API_KEY' with the browser key that you saved in Enable the Google Maps APIs for your Firebase survey.

  5. Create a new file for the backend configuration: ground-platform/web-ng/src/environments/.backend-config.json
  6. Add the following code to the file:

     {
     "offlineBaseMapSources": []
     }
    
  7. Create a new file for the Firebase configuration: ground-platform/web-ng/src/environments/.firebase-config.ts
  8. Add code snippet that you copied from the config page in Add the web app to your Firebase survey.
  9. Adding export before const, the contents of the file should look roughly like this:

     export const firebaseConfig = {
         apiKey: 'soMeReallYlOngApIkeyWouLdGoHere123',
         authDomain: 'my-app.firebaseapp.com',
         databaseURL: 'https://my-app.firebaseio.com',
         surveyId: 'my-app',
         storageBucket: 'my-app.appspot.com',
         messagingSenderId: '12345678',
         appId: '1:12345678:web:abc123etcetc',
     };
    
  10. In a terminal window, from the ground-platform directory:
    1. Run nvm install 14 && nvm use 14
    2. Run npm install -g @angular/cli firebase-tools
    3. Run firebase use <your-Firebase-survey-id>
    4. Run ./build.sh
    5. Run firebase deploy
  11. Once deployment is complete, test the app by going to https://<your-Firebase-survey-name>.web.app

3. Configure and build the Android app

After deploying the Ground web app, you can build the Android app. Like the web app, the source files for the Android app are stored on GitHub. You can download the source files and then use Android Studio to build the application. After you build the app, you also need to add the certificate fingerprint to your Firebase survey, so that the Ground services can authenticate your app.

Build the Android app

  1. In a terminal window, in the directory where you want to download the Android app source code, run git clone https://github.com/google/ground-android.git
  2. Within ground-android/gnd/src/ create a debug/ directory.
  3. Add the google-services.json that you downloaded in Add the Android app to your Firebase survey to ground-android/gnd/src/debug/.
  4. Within ground-android/gnd/, create a secrets.properties file and add the following text (using the Android API key that you copied in Enable the Google Maps APIs for your Firebase survey): GOOGLE_MAPS_API_KEY=<your-Android-Maps-API-key>
  5. Open Android Studio.
  6. Select File > New > Import Survey.
  7. Select the ground-android directory and click Open.
  8. At the bottom-right corner of the window, click Event Log.
  9. Click Install required plugins.
  10. Click OK.
  11. Click Accept.
  12. Click Restart to activate plugin updates.
  13. After restarting, at the bottom-right corner of the window, click Enable for this survey.
  14. Select Build > Build Bundle(s) / APK(s) > Build APK(s).
  15. In the Build APK(s) notification that appears at the bottom-right corner of the window when the build completes, click locate to open the directory that contains the app APK.

For information on distributing and installing the APK, see Distributing the Android app.

Retrieve and add the certificate fingerprint to your Android app configuration in Firebase

  1. Open a terminal window and navigate to your home directory.
  2. Run: keytool -list -v -keystore .android/debug.keystore -alias androiddebugkey -storepass android -keypass android
  3. Copy the SHA-1 certificate fingerprint value.
  4. From the left nav on the Firebase survey page, click the settings gear next to Survey Overview and select Survey Settings.
  5. In the Your apps section, select your Android app.
  6. Click Add fingerprint.
  7. Paste the SHA-1 value that you retrieved from the keystore.
  8. Click Save.

4. Share Ground web login details and distribute the Android app

Once you configure and build the Ground apps, you can share them with your survey collaborators.

Note: Before sharing the apps, make sure to add the collaborators’ email addresses or domains to the passlist in Firebase.

Sharing the web app

  1. Go to https://<your-Firebase-survey-name>.web.app
  2. Create a new survey.
  3. In the top-right corner of the screen, click Share.
  4. Add collaborators:
    1. Enter the collaborator’s email address.
    2. Select a role.
    3. Click Add.
  5. Click Save.
  6. Copy the page URL for the survey. This URL should be the app URL followed by /survey/<Ground-survey-ID>
  7. Send the survey URL to the collaborators.

Note: When you add a collaborator from the Share with collaborators window, they do not automatically receive a notification via email. You need to manually send them the survey URL. Also, if the collaborator is prompted to create a survey after signing into Ground for the first time, they may need to reload the survey URL.

Distributing the Android app

The easiest way to distribute the Android app is to upload the gnd-debug.apk file generated in 3. Configure and build the Android app to Google Drive and then share the file with your survey collaborators. When users open the link on their Android devices, they will be prompted to download and install the app.

Note: Depending on the user’s Android settings, they may need to allow apps from unknown sources. The location of this setting varies between Android versions. In Android 11, this setting must be enabled for the app that distributes the unknown app (Google Drive) within Settings > Apps & notifications > Advanced > Special app access > Install unknown apps.

Troubleshooting

The Android build or Gradle sync fails

If the build or Gradle sync fails, first check the Event Log and Build panels for errors. Then, make sure you have the following SDK tools installed:

You can view and install SDK tools from Android Studio > Preferences > Appearance & Behavior > System Settings > Android SDK > SDK Tools.

Collaborators can’t sign into the survey

Make sure that you have created a passlist collection to your Firestore instance and added all of your collaborators.

You can view and edit your passlist on the Cloud Firestore page of your Firebase survey by selecting Firestore Database within the Build section of the left nav. The first column on the Data tab contains a list of your survey’s collections, one of which should be named passlist. The passlist collection should contain separate documents for each user that you want to have access to the survey, with the user’s Google account (e.g. name@gmail.com) as the Document ID. There are no required fields for documents, but you may want to create fields to keep track of the user’s organization or who they were added by.

Collaborators can’t access the Ground survey after signing into the web app

If the collaborator is prompted to create a survey after signing into Ground for the first time, they may need to reload the survey URL:

https://<your-Firebase-survey-name>.web.app/survey/<Ground-survey-ID>

Collaborators can’t access the Ground survey after signing into the Android app

Make sure that you share the Ground survey with collaborators using the web app. You can also view and modify the users for each survey from the Firestore console in Firebase. Users for each survey are listed in the acl field of the survey document within the surveys collection.