Java 17 is now available in preview.

Testing and Deploying your Application

Region ID

The REGION_ID is an abbreviated code that Google assigns based on the region you select when you create your app. The code does not correspond to a country or province, even though some region IDs may appear similar to commonly used country and province codes. For apps created after February 2020, REGION_ID.r is included in App Engine URLs. For existing apps created before this date, the region ID is optional in the URL.

Learn more about region IDs.

Learn how to run your application locally, deploy it, and test on App Engine.

Running locally

To test your application's functionality before deploying, run your application in your local environment with the development tools that you usually use.

Before deploying your application

Before you can deploy your application:

Deploying your application

You can use any of the following techniques to deploy your app:

To programmatically deploy your apps, use the Admin API.

Deploying your app's source code

If you use Maven or Gradle to manage your app's local builds, and if all of your app's dependencies are publicly available for download, you can enter the gcloud app deploy command from the directory that contains your app's pom.xml or build.gradle file:

gcloud app deploy

The command instructs Cloud Build to use App Engine Buildpacks to build your app and deploy it to App Engine.

If you use Maven:

  • The buildpack uses the following build command: mvn clean package --batch-mode -DskipTests

  • If your app's root directory contains a mvnw file, the build command substitutes ./mvnw in place of mvn. Cloud Build then looks in the target directory for the .jar file with a Main-Class manifest entry and creates an entrypoint with the value java -jar <jarfile>.

If you use Gradle:

  • The buildpack uses the following build command: gradle clean assemble -x test --build-cache

  • If your app's root directory contains a gradlew file the build command substitutes ./gradlew in place of gradle. Cloud Build then looks in the build/libs directory for the .jar file with a Main-Class manifest entry and creates an entrypoint with the value java -jar <jarfile>.

  • Make sure there is no pom.xml in the root of your project. Maven projects take precedence over Gradle projects.

Viewing build logs

Cloud Build streams build and deploy logs, and you can view them in the Cloud Build history section of the Google Cloud console. To view builds in the app's region, use the Region drop-down menu at the top of the page to choose the region you would like to filter by.

Note the following about this deployment technique:

  • If your app has dependencies that are only available locally, Cloud Build is not able to build your app and your deployment will fail. In this case, we recommend using the App Engine Maven or Gradle plugin instead.

  • Building your app uses Cloud Build quota and storing your app's source code uses Cloud Storage quota. Cloud Build and Cloud Storage provide free quotas, so you won't incur costs from deploying App Engine apps until you surpass the free quotas. For information, see Pricing.

  • Currently, it isn't possible to specify additional arguments for the Gradle build command. For more information, see the Google Issue Tracker.

Using the App Engine Maven or Gradle plugin

App Engine provides Maven and Gradle plugins that you can use to build and deploy your app. For example, after you set up the App Engine Maven plugin, you can enter the following command from the directory that contains your project's pom.xml file:

mvn package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID

Replace PROJECT_ID with the ID of your Cloud project. If your pom.xml file already specifies your project ID, you don't need to include the -Dapp.deploy.projectId property in the command you run.

For more information, see Using Apache Maven and the App Engine Plugin or Using Gradle and the App Engine Plugin.

Deploying an executable JAR

Use any build framework to build an executable JAR locally, then do one of the following depending on whether you created an app.yaml file for your app:

  • If you created an app.yaml file:

    1. Copy the file into the same directory as the executable JAR file you created.

    2. From the directory that contains the app.yaml and your JAR, enter the following command:

      gcloud app deploy

  • If you haven't created an app.yaml file, enter the following command:

    gcloud app deploy your-executable.jar

    gcloud app deploy will create an app.yaml file that contains the minimum settings, using all default values.

Ignoring files

You can use a .gcloudignore file to specify files and directories that will not be uploaded to App Engine when you deploy your services. This is useful for ignoring build artifacts and other files that do not need to be uploaded with your deployment.

Managing build images

Each time you deploy a new version, a container image is created using the Cloud Build service. That container image is built in the app's region, and then runs in the App Engine standard environment.

Built container images are stored in the app-engine-tmp/app folder in Container Registry. You can download these images to keep or run elsewhere. Once deployment is complete, App Engine no longer needs the container images. Note that they are not automatically deleted, so to avoid reaching your storage quota, you can safely delete any images you don't need. For more information about managing images in Container Registry, see the Container Registry documentation.

Viewing your application

After you deploy your application to App Engine, you can run the following command to launch your browser and view it at https://PROJECT_ID.REGION_ID.r.appspot.com:

gcloud app browse

Testing on App Engine before shifting traffic

Before configuring a new version to receive traffic, you can test it on App Engine. For example, to test a new version of your default service:

  1. Deploy your new version, but prevent traffic from being automatically routed to the new version:

    mvn appengine:deploy -Dapp.deploy.projectId=PROJECT_ID -Dapp.deploy.promote=False

  2. Access your new version by navigating to the following URL:

    https://VERSION_ID-dot-default-dot-PROJECT_ID.REGION_ID.r.appspot.com

    Now you can test your new version in the App Engine runtime environment. You can debug your application by viewing its logs. For more information, see Writing Application Logs.

    App Engine routes requests sent to https://PROJECT_ID.REGION_ID.r.appspot.com to the version previously configured to receive traffic.

  3. When you want to send traffic to the new version, use the Google Cloud console to migrate traffic:

    Manage versions

    Select the version you just deployed and click Migrate traffic.

You can use the same process to test new versions of other services by replacing default in the URL with your service's name:

https://VERSION-dot-SERVICE-dot-PROJECT_ID.REGION_ID.r.appspot.com

For more information about targeting specific services and versions, see How Requests are Routed.

Using build environment variables

You can also set build environment variables for runtimes that support buildpacks.

Build environment variables are key/value pairs deployed alongside an app that let you pass configuration information to buildpacks. For example, you might want to customize compiler options. You can add or remove these build environment variables by configuring the build_env_variables field in your app.yaml file.

Using Cloud Debugger

You can use Debugger to inspect the state of your deployed app at any code location, without stopping or slowing down the running app.

To use Debugger with a Java 11 app, the following flag needs to be included in the entrypoint field of your app.yaml file:

-agentpath:/opt/cdbg/cdbg_java_agent.so=--log_dir=/var/log

If you have already specified the entrypoint in app.yaml, file add the agentpath flag to the java command in the entrypoint field.

If you haven't specified the entrypoint field, or if you generate the app.yaml file when you deploy your app, App Engine adds the flag to the command it uses to start your app.

Using Cloud Profiler

Cloud Profiler is a statistical, low-overhead profiler that continuously gathers CPU usage and memory-allocation information from your production applications. It attributes that information to your app's source code, helping you identify the parts of the app consuming the most resources, and otherwise illuminating the performance characteristics of the code.

To use Cloud Profiler, set up your app's configuration files as described in Starting your program and redeploy the app.