Google Cloud Starter: App Engine Flexible Environment

This is a starter project for Google Cloud App Engine Flexible Environment based on nodejs. It is implemented in JavaScript and provides a basic http service with cors, linting, unit tests, system tests and logging.

Prerequisites

1. Before you can start coding, make sure that gcloud is installed.

2. This starter also requires Node.js.

3. Fork this template project.

If you already have installed the prerequisites, then you're all set.

Set project name, project version, service name and node version

1. Open the file package.json and modify the name and version.

2. Edit config.service in package.json and service in app.yaml to change the service name.

3. Modify engines.nodes in package.json and replace all entries of gcr.io/cloud-builders/npm:node-X.X.X in cloudbuild.yaml with your required node version. Also update runtime in app.yaml accordingly.

4. Run npm install to apply the changes and update package-lock.json.

Install and run locally

1. Install package and its dependencies:

    npm install
   

2. Run eslint:

    npm run lint
   

3. Run unit tests:

    npm test
   

4. Start local instance:

    npm start
   

5. Open browser and navigate to http://localhost:8080/ or http://localhost:8080/gcp to invoke the service.

Prepare deployment

1. Billing must be enabled.

2. Configure project for gcloud:

    gcloud config set project [PROJECT_ID]
   

   Note: Replace [PROJECT_ID] with the Google Cloud project id.

3. Enable App Engine Flexible Environment.

4. Create an App Engine application:

    gcloud app create
   

   Note: Choose an App Engine location based on our requirements.

Deploy to Google Cloud

1. Deploy to google cloud:

    npm run deploy
   

   Or you can deploy a promoted version to receive all traffic:

    npm run deploy:promote
   

   Also consider to set a version:

    npm run deploy -- --version 1-0-0
   

2. Run system test:

    export BASE_URL="[BASE_URL]"
    npm run test:system
   

   Note: Replace [BASE_URL] with the target url to the app engine service, e.g. https://VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com or https://PROJECT_ID.REGION_ID.r.appspot.com.

3. Configure traffic to a version:

    npm run split -- --splits='[VERSION_ID]=1'
   

   Or split the traffic across two (or more) versions:

    npm run split -- --splits='[VERSION_ID_1]=.5,[VERSION_ID_2]=.5'
   

   Note: Replace [VERSION_ID] or [VERSION_ID_X] with the version of the service. If you are unsure, than list your existing versions: gcloud app versions list. Also consider to manage versions with Cloud Console.

4. Open service in browser: https://VERSION_ID-dot-SERVICE_ID-dot-PROJECT_ID.REGION_ID.r.appspot.com or https://PROJECT_ID.REGION_ID.r.appspot.com. Alternatively use the following command:

    gcloud app browse
   

Prepare build automation

1. The build process depends on Cloud Build. Please enable the Cloud Build API.

2. The service account of Cloud Build requires access to App Engine and Service Accounts. Open Cloud Build Settings to set the required permissions. Please also follow the instructions of the additional steps and enable the App Engine Admin API.

Build automation

Test, build and deploy the application as part of your automated pipeline:

    npm run cicd

Logging

By default, info level messages are logged. Modify the envrionment variable APP_LOG_LEVEL in app.yaml to change the logging level. The default logName is "projects/[PROJECT_ID]/logs/[PACKAGE_JSON_NAME]_log". This starter uses winston as logging library. Please read more about how to write log entries and about all possible logging levels on the project website.

License

Distributed under the MIT License. See LICENSE for more information.