Skip to content

Latest commit

 

History

History
237 lines (188 loc) · 9.92 KB

development.md

File metadata and controls

237 lines (188 loc) · 9.92 KB

Google Fleet Routing App - Development

Follow these steps to set up a local development environment for Fleet Routing App.

Google Cloud Project Setup

🛑 Before you can run the app, you will need access to a Google Cloud project with Optimization API other required services enabled. You will also need Service Account and API Key credentials to authenticate requests.

⏭️ If you have already deployed an instance of Fleet Routing App to a Google Cloud project, you can use the resources in that project for local development. Skip to the Local Environment Setup section.

If you don't have an existing deployment or don't wish to use it for development purposes, follow these steps to create a new project with the minimum requirements to run Fleet Routing App locally.

Prerequisites

  • Google account with rights to create Google Cloud projects in your organization
  • Google Cloud Billing Account to enable paid services
  • Google Cloud SDK installed and configured

    You can use Google Cloud Shell in a web browser to complete this setup without installing anything on your local machine.

Create Google Cloud Project

Run the following command to create a new Google Cloud project. If you are not a member of a Google Cloud organization, omit the --folder flag.

gcloud projects create {PROJECT_ID} --name={PROJECT_NAME} --folder={FOLDER_NUMBER}  --no-enable-cloud-apis

Use the --no-enable-cloud-apis flag here to prevent default services and resources (VPCs, service accounts, etc.) from being created. Later, you will explicitly enable just the services required by Fleet Routing App.

Take note of your new PROJECT_ID, you will use this value throughout the remaining steps.

Enable Billing

The application has a dependency on paid offerings from Google Maps Platform and therefore requires a project be linked to a billing account before the appropriate APIs can be enabled.

Follow the instructions in Google's documentation to enable billing for your new project.

Enable APIs

The frontend application depends on the following APIs:

  • Route Optimization API
  • Google Maps Distance Matrix
  • Google Maps for Fleet Routing
  • Google Maps Geocoding
  • Google Maps JavaScript API,
  • Google Maps Places
  • Google Maps Static Maps

Find and enable each of these APIs in the APIs & Services > Library section of Cloud Console or run the following gcloud commands:

# optimization
gcloud services enable routeoptimization.googleapis.com --project {PROJECT_ID}
# distance matrix
gcloud services enable distance-matrix-backend.googleapis.com --project {PROJECT_ID}
# geocoding
gcloud services enable geocoding-backend.googleapis.com --project {PROJECT_ID}
# maps javascript
gcloud services enable maps-backend.googleapis.com --project {PROJECT_ID}
# places
gcloud services enable places-backend.googleapis.com --project {PROJECT_ID}
# static maps
gcloud services enable static-maps-backend.googleapis.com --project {PROJECT_ID}

Create API Key

Create an API key to enable the frontend to use the required Google Maps APIs.

  1. Go to Google Cloud Console and open your project

  2. Navigate to the APIs & Services > Credentials section

  3. Click the +Create Credentials button at the top of the screen, and select API key

  4. In the resulting window click Edit API key to open the API Key details page. Give it a meaningful name (e.g. "Fleet Routing Maps") and leave the key unrestricted.

Create Service Account

Create a service account in your Google Cloud project to authenticate Optimization API requests from Fleet Routing App.

Run the following gcloud command to create a fleetrouting-app Service Account in your project:

gcloud iam service-accounts create fleetrouting-app \
  --display-name="Fleet Routing App Service Account" \
  --project={PROJECT_ID}

IAM

Grant your new service account the Route Optimization Editor (roles/routeoptimization.editor) role, which is required for Route Optimization requests.

Add the role to the service account's permissions in the IAM & Admin > IAM section of Cloud Console, or run the following gcloud command:

gcloud projects add-iam-policy-binding {PROJECT_ID} \
  --member=serviceAccount:fleetrouting-app@{PROJECT_ID}.iam.gserviceaccount.com \
  --role=roles/routeoptimization.editor

Local Environment Setup

Prerequisites

Clone the Repository

This single repository contains both the backend and frontend packages for Fleet Routing App. Clone the repository and navigate to the checked-out directory.

git clone https://github.com/googlemaps/js-route-optimization-app.git
cd js-route-optimization-app

Install Dependencies

The application uses Lerna to build and run the backend and frontend packages side-by-side for local development.

Navigate to the application directory and install the dependencies with npm.

cd application
npm install

ℹ️ After installing top-level application dependencies, the lerna init and lerna bootstrap commands will run to install dependencies in the backend and frontend sub-packages.

Configure Environment Variables

Create a .env environment variable file at application/.env.

Populate application/.env file with the details of your Google Cloud project as follows:

Varable Name Description Default
Required
PROJECT_ID ID (not number) of your Google Cloud project, a.k.a. Optimization API "parent" project
API_ROOT URL of the backend API (probably http://localhost:8080/api)
FRONTEND_PROXY URL of the frontend Angular development server (probably http://localhost:4200/) - FOR DEVELOPMENT USE ONLY
MAP_API_KEY API Key to load Google Maps JavaScript API in frontend (see Authentication section)
GOOGLE_APPLICATION_CREDENTIALS Path to a service account credentials JSON file to authenticate Google API requests (see Authentication section) Default application credentials
Optional
LOG_FORMAT Log format to output (google or pretty) google
LOG_LEVEL Minimum Pino log level to output info
GRPC_TRACE gRPC component(s) to show internal logs for (or set to all to log every component). See gRPC Troubleshooting guide. If not set, no internal gRPC logs are enabled
GRPC_VERBOSITY Minimum gRPC log level to output (when GRPC_TRACE is enabled). ERROR
ALLOW_USER_GCS_STORAGE When true, allow user to save scenario/solution files in a Cloud Storage bucket (see STORAGE_BUCKET_NAME) false
STORAGE_BUCKET_NAME (Optional) Storage bucket to save scenario/solution files (when ALLOW_USER_GCS_STORAGE is enabled)
STORAGE_PROJECT_ID ID of the project that owns the Storage bucket referenced in STORAGE_BUCKET_NAME (if different than PROJECT_ID) If not set, PROJECT_ID is used
STORAGE_CREDENTIALS Path to a service account credentials JSON file to authenticate Storage API requests (if different than default or GOOGLE_APPLICATION_CREDENTIALS) Default application credentials

Template:

PROJECT_ID={YOUR_PROJECT_ID}
API_ROOT=http://localhost:8080/api
FRONTEND_PROXY=http://localhost:4200/
GOOGLE_APPLICATION_CREDENTIALS={PATH_TO_SERVICE_ACCOUNT_KEY}
MAP_API_KEY={YOUR_API_KEY}
LOG_LEVEL=debug
LOG_FORMAT=pretty

Authentication

Service Account Credentials

To authenticate requests to Route Optimization, the backend needs credentials for a Google Cloud service account with the Route OptimizationEditor role.

ℹ Route Optimization requests cannot be authenticated with end-user credentials.

Create a JSON service account key for the Fleet Routing App Service Account (fleetrouting-app@) in your project. Save it to your machine and set the absolute path of the downloaded credentials JSON file as the GOOGLE_APPLICATION_CREDENTIALS environment variable (see Configure Environment Variables section).

API Key for Google Maps

To load Google Maps JavaScript API and make other requests to Google Maps Platform APIs, the frontend needs an API Key.

Locate your API Key in the APIs & Services > Credentials section of Cloud Console. Copy its value and set it as the MAP_API_KEY environment variable (see Configure Environment Variables section).

Run the App

To run the backend and frontend together in development mode, navigate to the application directory and run npm start. Lerna will start both packages in parallel:

  • backend will start in "watch" mode, recompiling and restarting the server when changes are detected
  • frontend will start the Angular development server (ng serve)
cd application
npm start

💡 Expect the backend to start near-instantly. However, the frontend may take several minutes until it's ready, depending on the speed of the Angular build.

After the frontend Angular build finishes, open http://localhost:8080 in your browser to view the app.