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 projects, 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 project
  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 project

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

  1. Go to https://console.firebase.google.com/ and log into your Firebase account.
  2. Click Create a project.
  3. Enter a project name, accept the terms, and click Continue.
  4. Make sure that Enable Google Analytics for this project 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 project.

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 project 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 project 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 project owner (optional)

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

  1. From the left nav on the Firebase project page, click the settings gear next to Project 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 project 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 projects 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 projects hosted in your new Firebase project. This passlist is a collection of documents within the project’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 project 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 projects. 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 project 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 project billing plan to Blaze

By default, Firebase projects 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 project page, click the settings gear next to Project 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 project

In order for the Ground Android app to access Firebase services, you must first add it to your Firebase project. 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 project page, click Project 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 project.
  6. Click Next.
  7. Click Next.
  8. Click Continue to console.

Add the web app to your Firebase project

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

  1. From the left nav on the Firebase project page, click Project 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 project page, click the settings gear next to Project Overview and select Project 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 project

Both the Android and web apps for Ground use the Google Maps API, so you need to enable the Maps SDK for your project 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 project is not the project you created in Firebase for Ground, click project name in the top menu bar and select your Ground project.
  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 project 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 project.

  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 project.
  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',
         projectId: '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-project-id>
    4. Run ./build.sh
    5. Run firebase deploy
  11. Once deployment is complete, test the app by going to https://<your-Firebase-project-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 project, 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 project 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 project): GOOGLE_MAPS_API_KEY=<your-Android-Maps-API-key>
  5. Open Android Studio.
  6. Select File > New > Import Project.
  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 project.
  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 project page, click the settings gear next to Project Overview and select Project 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 project 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-project-name>.web.app
  2. Create a new project.
  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 project. This URL should be the app URL followed by /project/<Ground-project-ID>
  7. Send the project 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 project URL. Also, if the collaborator is prompted to create a project after signing into Ground for the first time, they may need to reload the project 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 project 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 project

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 project by selecting Firestore Database within the Build section of the left nav. The first column on the Data tab contains a list of your project’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 project, 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 project after signing into the web app

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

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

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

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