Google Cloud Starter: App Engine Flexible Environment with custom runtime

This is a starter project for Google Cloud App Engine Flexible Environment with custom runtime based on nodejs maintained by the Node.js Docker Team. 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. Docker is optional.

4. Fork this template project.

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

Rename project, version and service

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.

Optional steps to build and run Docker image on local system:

1. Build Docker image with Cloud Build Local (requires Docker):

    npm run build:local
   

2. Run Docker image:

    docker -p 8080:8080 [IMAGE]
   

   Note: Replace [IMAGE] with name of the image. List images with docker image ls.

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. The build process depends on Cloud Build. Please enable the Cloud Build API.

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

5. Enable App Engine Flexible Environment.

6. Create an App Engine application

    gcloud app create
   

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

Deploy to Google Cloud

1. Submit a build to Cloud Build, which creates the Docker image and uploads it to the Container Registry:

    npm run build
   

2. Deploy the application:

    npm run deploy
   

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

    npm run deploy:promote
   

3. If required, start the deployed version:

    gcloud app versions start [VERSION_ID]
   

   Note: Replace [VERSION_ID] with the version of the service.

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

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

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

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. Add or 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.

Troubleshooting

1. If your run into issues during build or deployment , append -- --verbosity debug to the command:

    npm run build -- --verbosity debug
   

2. Open the Cloud Build history and view the logs of the failed builds.

3. Review Cloud Build service account permissions and assigned roles that grant access to App Engine.

License

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