Skip to content

Ground Developer's Guide

Jump to bottom
Gino Miceli edited this page Jun 10, 2024 · 23 revisions

Overview

This guide explains how to build, deploy, and contribute to the Ground web and Android apps. This includes building both apps from source code hosted on GitHub, as well as setting up and deploying to your own Firebase project.

Prerequisites

To build Ground from source code you will need the following:

  • A computer running macOS or Linux. Building and deploying from Windows is not yet supported (see #1438).
  • A basic understanding of command-line tools. You do not need to be proficient in Firebase, Angular, or Android development unless you want to modify or contribute to Ground's source code, but some knowledge of development tools and system administration will be helpful.

Set up your environment

Install the following software packages by clicking each link and following the instructions found there:

Lastly, install Node.js by running the following in a terminal:

Get the source code

To keep your work organized, create a directory to hold the Ground source code and your work, for example:

Then, clone the source code from GitHub to that directory by running:

git clone https://github.com/google/ground-platform.git
git clone https://github.com/google/ground-android.git

Create Android Studio project

  1. Open Android Studio
  2. In the welcome screen, click Open
  3. Select ~/Ground/ground-android (or whatever location you used when you cloned the source code from GitHub).
  4. When prompted, click Trust Project

Run locally (optional)

Follow steps in this section to quickly test Ground without setting up a Firebase project. If you only want to deploy to your own dev or prod Firebase project without first testing locally, you can skip this section.

Run the web app and Firebase emulator locally

Switch to the ground-platform dir with:

To install dependencies, build, and run the Ground web app and Cloud Functions locally in the Firebase Local Emulator Suite, run:

npm run start:local

Once the local server is ready, access the web app at http://localhost:5000. For development, and testing, the Firebase Emulator Suite UI is accessible at http://localhost:4000. Changes to the web app in web/ and to Cloud Functions in functions/ are automatically rebuilt and reloaded on save.

Note: The local build variant does not require API keys to run, so you can expect to see warnings related to missing API keys. Authentication is also disabled.

The local emulator is preloaded with a demo survey. Run npm run export:local to save the updated demo data to the local filesystem for use on the next run.

Run the Android app against the local Firebase emulator

To run Ground in an Android emulator with the Firebase emulators started above:

  1. Create an AVD, selecting an image with Play Service, as indicated by the "Play" icon next to the image.
  2. Wait for Gradle sync to complete if it hasn't already finished.
  3. In the top menu, click Build > Select Build Variant…
  4. Under the Build Variants panel, change the Active Build Variant for :ground to localDebug. The active variant for :sharedTest will change automatically to match.
  5. In the top menu, click Run > Run ‘ground'. Alternatively, you can click the "Run toolbar" button, or press ^R.

Build and deploy to Firebase

Set up a Firebase project

In order to build and deploy Ground for production use, or to perform end-to-end testing during development, you need to have a Firebase project with an active Cloud Billing Account. Specifically, Ground relies on several Firebase services to function: Cloud Firestore, Security Rules, Cloud Functions, Authentication, access to Cloud Storage, and Crashlytics.

Even if you already have an existing Google Cloud or Firebase project, we recommend creating new Firebase projects for your organization's development and production instances of Ground.

Create a Firebase project

  1. Log in to your Firebase account at https://console.firebase.google.com/.

  2. Click Create a project.

  3. Enter a human-readable project name, for example "Ground - Acme Corp"

  4. Accept the Terms of Service and click Continue.

  5. Click Create project.

Modify the Firebase billing plan

By default, Firebase projects use the free Spark plan. However, Ground requires services which are not included in the Spark plan. As such, Ground only works on Firebase projects which use the pay-as-you-go Blaze plan. For more on free quota and paid usage, see Firebase Pricing.

To switch to the Blaze plan:

  1. From the left nav on the Firebase project page, click the gear icon next to Project Overview and select Usage and billing from the menu.
  2. Select the Details & settings tab.
  3. Click Modify plan.
  4. Under Blaze Pay as you go, click Select plan.
  5. Click Purchase.
  6. Click Set a budget alert, enter an amount, and click Set budget alert.

Create a Firestore database

Cloud Firestore is used for storing Ground user data. To create a database:

  1. From the left nav on the Firebase project page, select Build > Firestore Database.
  2. Click Create database.

    1. Set name and location. For more information about selecting a location, see Location considerations.

      1. Secure rules. Select Start in production mode and click Create.

Create a Cloud Storage bucket

Cloud Storage is used for storing Ground user media and offline imagery. To create a storage bucket:

  1. From the left nav on the Firebase project page, select Build > Storage.
  2. Click Get started.
  3. Secure rules. Select Start in production mode.
  4. Set Cloud Storage location and click Done. For more information about selecting a location, see Location considerations.

Enable Google sign-in

Ground relies on Firebase for its "Sign in with Google" functionality. To enable Google sign-in, complete the following steps:

  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 project name, which will appear on the sign-in dialog, for example "Ground - Acme Corporation".
  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, grant them "owner" access by completing the following steps:

  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 has access to Ground via the web and Android apps. Firebase permissions only control who can administer the backend via the Firebase console and command-line tools.

Install the Resize Images Extension

Ground uses the Resize Images Firebase extension to automatically generate thumbnails of photos uploaded by data collectors. To install it, complete the following steps:

  1. From the left nav on the Firebase project page, click Build > Extensions.

  2. Click Explore Extensions

  3. Under Resize Images, click Install.

  4. Click Next.

  5. Activate required services

  6. Click Next.

  7. Click Next.

  8. In the Configure extension section, specify the following values exactly as shown here:

  • Size of reduced images: 200x200
  • Deletion of original file: Don't delete
  • Paths that contain images you want to resize (Optional): /user-media
  • Convert image to preferred types: original
  1. Backfill: No
  2. Deselect "Activate events"
  3. Click Install extension

Register the web app

In order for the Ground web app to access Firebase services, you must first add it to your Firebase project. To add the web app, complete the following steps:

  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.
  3. In the App nickname field, enter a human-readable nickname for the web app, for example "Ground - Acme Corp".
  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 and paste the code snippet into a new file in ~/Ground/ground-platform/web/keys/<project-id>/firebase-config.js, which is the id of your Firebase project.

Register the Android app

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

Each Android build is signed with a key which needs to be registered with Firebase. A debug key is generated automatically the first time you build an app in Android studio. If this is your first time building an Android app, run the following to generate a new debug build key if one doesn't already exist:

Once you have the key for your app, add it to Firebase:

  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. If you're using an existing project, the icon will appear at the top of the page directly under the Firebase project.

  3. Under Register app, enter the following values:

  4. Android package name: com.google.android.ground

  5. App nickname: Enter any nickname you want

  6. Debug signing certificate SHA-1: still in the ~/.android directory, run the following command the display your debug key's fingerprint:

    Copy and paste SHA-1 certificate fingerprint displayed there.

  7. Click Register app.

  8. Click Download google-services.json and select the ~/Ground/ground-android/ground/src/debug/dev directory.

  9. Click Next.

  10. Click Next.

  11. Click Continue to console.

Enable Google Maps APIs

The Android and web apps for Ground use the Google Maps SDK for Android and Google Maps JavaScript API, respectively. Enable them in the Google Cloud Console by completing the following steps:

  1. 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.

  2. Click Enable.

  3. Open Maps SDK for Android in Google Cloud Console.

  4. Click Enable.

Once you enable the API and SDK in the Cloud Console, credentials generated by Firebase can access these services, so you don't need to take any further action to create and use credentials in the Ground apps.

Grant users access to Ground

Ground uses a special collection Firebase Cloud Firestore to control which users can sign in to the Ground apps. This passlist is a collection within the project's Firestore database in which the IDs of the documents are the email addresses of the users with access. To create and manage the passlist, complete the following steps:

  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 a user to the collection by entering the user's email address as the Document ID. Optionally, you may add useful metadata or notes by adding field-value pairs 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 use 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 the email address of users allowed to access Ground. For example, to add all users for the @example.com domain, you would enter .*@example[.]com as the value of the regexp field in the regexp document.

Build and deploy

Build and deploy the web app and backend

To build and deploy the web app, Cloud Functions, and other Ground Firebase services, from the command line, run:

cd ~/Ground/ground-platform && npm run deploy:dev --project=<project-id>

Once the deployment is complete, the Ground web app will be accessible at https://<project-id>.web.app

Note: We recommend creating separate projects for your dev and prod environments. If you're not contributing to Ground, you can typically deploy directly to your prod environment.

Android app

  1. Open your Ground project in Android Studio.
  2. Wait for Gradle sync to complete if it hasn't already finished.
  3. In the top menu, click Build > Select Build Variant…
  4. Under the Build Variants panel, change the Active Build Variant for :ground to devDebug. The active variant for :sharedTest will change automatically to match.
  5. In the top menu, click Run > Run ‘ground'. Alternatively, you can click the "Run toolbar" button, or press ^R.

Contribute

Community contributors

This section describes special instructions for community contributors wanting to contribute Ground code.

Read the Code of Conduct

Help us keep the Ground project open and inclusive. Please read and follow Google's Open Source Community Guidelines when contributing.

Accept the Contributor License Agreement (CLA)

Contributions to this project must be accompanied by a Contributor License Agreement. You (or your employer) retain the copyright to your contribution; this agreement gives us permission to use and redistribute your contributions as part of the project. Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one.

You generally only need to submit a CLA once, so if you've already submitted one (even if it was for a different project), you probably don't need to do it again.

Fork the repo(s)

As a community contributor, you must push code changes to your own fork of the main "upstream" repo before it can be accepted. To fork the repo(s), complete the following steps::

  1. Fork google/ground-platform and/or google/ground-android, depending on whether you will be making changes to the web and/or Android apps, respectively.

  2. Update your local clones set up earlier in this guide to point to your new fork. For web, Cloud Functions, and other hosted components:

    For Android:

Where <user> is your GitHub username.

You can now pull the latest upstream changes into your local clone with git pull upstream master, or push and pull from your own fork with git push and git pull, respectively.

Developer workflow

Claim an issue

Before you begin work on a change, comment on one of the open issues in github.com/google/ground-platform/issues or github.com/google/ground-android/issues expressing your interest. If an issue does not already exist for the fix you had in mind, you can also createone at github.com/google/ground-platform/issues/new and github.com/google/ground-android/issues/new.

Create a branch

Before you begin making code changes, create a branch for the change you're about to make. First, make sure you have the latest commits in your local clone:

Maintainers: Omit "upstream master".

Next, create a branch with names of the form <user>/<issue-no>/<short-desc>. For example:

Writing and testing code

Write your changes locally, committing them to the new branch with brief, meaningful commit messages. Before submitting code for review, be sure you've manually tested your change, and that all tests and checks are passing.

Android

To run tests in Android Studio, right-click the ground-android/ground folder in the Project pane and click "Run 'All tests'".

Web and Backend

If you plan to edit the web or backend source code, you should also install:

Create a pull request

You're now ready to submit your first change. All changes require review and approval by at least one maintainer, including those submitted by maintainers themselve. We use GitHub pull requests for this purpose.

When creating a new pull request, be sure to replace template fields, especially the PR title and Fixes #<issue no> field in the comment field.

For more information about creating pull requests, see https://help.github.com/articles/creating-a-pull-request/. To learn more about referencing issues in your pull request or commit messages, see https://help.github.com/articles/closing-issues-using-keywords/.

Creating new issues

When filing new issues, be sure to fill out any fields included in the templates. In addition, add the following project fields:

Size:

XS = < 1 day S = about 1 day

M = about 3-5 days

L = about 5-8 days

XL = 10 days or more

Troubleshooting

User can't sign in to the Ground web or mobile app

Make sure that you've added the user to the passlist as described above and that the user is using the same email address that's in the passlist to log in to the app. Ensure capitalization and punctuation exactly match the format used by the user to log in.

Users don't see my survey in the Android app

Make sure you've shared your Ground survey with data collectors via the web app.

Clone this wiki locally