Deploying a Java App

Deploy your app to upload and run it on App Engine. When you deploy your apps, you create versions of those apps and their corresponding services in App Engine. You can deploy entire apps, including all the source code and configuration files, or you can deploy and update individual versions or configuration files.

To programmatically deploy your apps, use the Admin API.

Before you begin

Before you can deploy your app:

To deploy your app using the Maven build tool, you must set up your project to use the Maven plugin for App Engine.

Installing the gcloud command line tool

To deploy your app with the gcloud tool, you must download, install, and initialize the Cloud SDK.

Download the SDK

If you already have the gcloud tool installed and want to configure it to use a Cloud project ID other than the one that you initialized it to, see Managing Cloud SDK Configurations.

Using a proxy

If you are running the deployment command from a system which uses an HTTP or HTTPS proxy, you must configure the tool so that it can communicate via the proxy.


Run the following commands to configure the gcloud tool:

gcloud config set proxy/type [PROXY_TYPE]
gcloud config set proxy/address [PROXY_ADDRESS]
gcloud config set proxy/port [PROXY_PORT]

You can also set a username and password for the proxy. For more information, see gcloud config.


Set the environment variable that corresponds to your proxy:

Mac / Linux
export HTTP_PROXY=""
export HTTPS_PROXY=""

Deploying an app

To deploy your app to App Engine, you use either the Maven build tool (recommended), the appcfg tool, or the gcloud app deploy command from within the root directory of your application.

To deploy your app with the Maven build tool, run the following command from your project's top level directory, where the pom.xml file is located.

Using appcfg

To deploy your app, run the appcfg command with the update action and the directory path of your WAR file, for example:


appengine-java-sdk\bin\appcfg.cmd [options] update [WAR_LOCATION]

Mac / Linux

./appengine-java-sdk/bin/ [options] update [WAR_LOCATION]

If you are using an HTTP proxy, include the --proxy argument to tell appcfg its address. If you use a different proxy for HTTPS, then also include the --proxy_https argument. See the appcfg command line arguments for more information.


appengine-java-sdk\bin\appcfg.cmd --proxy= update [WAR_LOCATION]

Mac / Linux

./appengine-java-sdk/bin/ --proxy= update [WAR_LOCATION]

By default, the initial version that you deploy to a service is automatically configured to receive 100% of traffic. However, all subsequent versions that you deploy to the same service must be manually configured, otherwise they receive no traffic.

The tool automatically uses the application ID from your appengine-web.xml file. However, many of our sample applications omit <application> from the appengine-web.xml file, as well as <version>. Therefore, you must ensure that a Cloud project ID is specified for the application ID along with the version ID of your choice, for example:


appengine-java-sdk\bin\appcfg.cmd -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]

Mac / Linux

./appengine-java-sdk/bin/ -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]

If you deploy a version that specifies the same version ID as a version that already exists on App Engine, the files that you deploy will overwrite the existing version. When you overwrite your application, traffic can be disrupted. We recommend that you deploy your application with a unique version ID and migrate traffic to the new version.

Using gcloud command line

gcloud app deploy [YOUR_DEPLOYMENTS]

Where [YOUR_DEPLOYMENTS] is one or more configuration file's path and name, separated with a single whitespace.

Optional flags:

  • Include the --version flag to specify a custom version ID, otherwise one is generated for you.
  • To deploy your app without automatically routing all traffic to that version, include the --no-promote flag.
  • Include the --project flag to specify an alternate Cloud project ID to what you initialized as the default in the gcloud tool.

By default, each version that you deploy is automatically configured to receive 100% of traffic. For configuration options, see the --promote flag in the gcloud app deployreference.

Tip: Run gcloud help from the command line for a complete list of arguments and flags.

Choosing unique version IDs

For manually-scaled instances, the ID of your version should begin with a letter to distinguish them from numeric instance IDs. This ensures that requests are routed to the correct destination and avoids the ambiguity with URL patterns like 123-dot-my-service.[REGION_ID], which can be interpreted two ways:

  • If version 123 exists, the request is routed to version 123 of the my-service service.
  • If version 123 does not exist, the request is instead routed to instance ID 123 where the versions of the my-service service are running.

You can name your versions however you like for instances that are configured for auto scaling or basic scaling because targeting those instances is not supported.

Deploying multiple service applications

When your application is factored into multiple services, you can deploy and update individually targeted services or all the services simultaneously. Deploying updates to services can include updating individual configuration files or updating the source code in the corresponding versions.

For example, you can deploy and create two versions in App Engine, where each version runs in their own service. The first version serves as the frontend service and the other as the backend of your app. You can then deploy individual configuration files to update only the settings of a service. You can also choose to deploy a new version to a service in order to update the source code of the frontend, backend, or both simultaneously.

Requirements for multiple services

You use the same deployment commands for deploying and updating the multiple services of your application with the following requirements:

  • You must initially deploy a version of your app to the default service before you can create and deploy subsequent services.

  • You must specify the ID of your service in the appengine-web.xml configuration file of the corresponding version. To specify the service ID, you include the module: [YOUR_SERVICE_ID] element definition in each configuration file. By default, excluding this element definition from your configuration file deploys the version to the default service.

  • You must specify all the corresponding appengine-web.xml configuration files in your deployment command to simultaneously deploy multiple services. The default service must be listed first.

To deploy multiple services

From the root directory of the application where the configuration files are located, you run the deployment command and specify the relative paths and file names for each service's appengine-web.xml file.

Using the Maven build tool

If the root directory of your project contains only your services, you can deploy all those services with a single Maven command.

The Maven deployment command iterates through each of your project’s services to locate their configuration files and then deploy each service.

To deploy multiple services using the Maven plugin:

  1. Ensure that appengine-maven-plugin has been added to your parent pom.xml file.
  2. Run the following command:

    mvn appengine:deploy

Using gcloud

    gcloud app deploy [DEPLOYMENTS]

Where [DEPLOYMENTS] is one or more configuration file's path and name. You separate each configuration file that you specify with a single white space.

Using appcfg


appengine-java-sdk\bin\appcfg.cmd update [DEPLOYMENTS]

Mac / Linux

./appengine-java-sdk/bin/ update [DEPLOYMENTS]

Where [DEPLOYMENTS] is one or more configuration file's path and name, separated by a single whitespace. For example:


appengine-java-sdk\bin\appcfg.cmd update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]

Mac / Linux

./appengine-java-sdk/bin/ update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]

You will receive verification via the command line as each service is successfully deployed.

Updating indexes

To create or update the indexes that your apps use, upload the datastore-indexes.xml configuration file to Datastore. Indexes that don't exist yet are created after that configuration file is uploaded.

It can take a while for Datastore to create all the indexes and therefore, those indexes won't be immediately available to App Engine. If your app is already configured to receive traffic, then exceptions can occur for queries that require an index which is still in the process of being built.

To avoid exceptions, you must allow time for all the indexes to build, for example:

  • Upload the index.xml configuration file to Datastore before you deploy your version:

    1. Upload the index.xml file to Datastore:

      appcfg update_indexes [YOUR_APP_DIR]
    2. Use the Cloud Console to monitor the status of all your indexes:

      Go to the Datastore page

    3. After all your indexes are built, deploy the new version to App Engine.

  • Build your indexes before migrating or splitting traffic to your version:

    1. Define a new version ID in your app's appengine-web.xml file.
    2. Deploy the new version.
    3. Use the Cloud Console to monitor the status of all your indexes:

      Go to the Datastore page

    4. After all your indexes are built, use the Cloud Console to migrate or split traffic to your version:

      Go to the Versions page

For more information about indexes, see Configuring Datastore Indexes.


The following are common error messages that you might encounter:

PERMISSION_DENIED: Operation not allowed
The "appengine.applications.create" permission is required.
If the Cloud project does not include the required App Engine application, the gcloud app deploy command can fail when it tries to run the gcloud app create command. Only accounts with Owner role have the necessary permissions to create App Engine applications.
Command not found

If you did not create symlinks for the or tools when you installed the (deprecated) App Engine SDK, you might need to specify the full directory path to run the tool, for example: [PATH_TO_APP_ENGINE_SDK]/ or [PATH_TO_APP_ENGINE_SDK]/ .

Import Error

If you installed both the Cloud SDK as well as the original App Engine SDK, the entries to your PATH might conflict with one another and cause import errors. If you received errors when running Cloud SDK commands, try explicitly using the original App Engine SDK. You can move the entry for the original App Engine SDK to earlier in your PATH so that those commands have priority. Alternatively, you can run the command by specifying the full directory path: [PATH_TO_APP_ENGINE_SDK]/
Tip: On Linux or Mac, you can run which to determine which SDK is first in your PATH.

[400] The first service (module) you upload to a new application must be the 'default' service (module)

Before you can deploy and create the multiple services of your application, you must first deploy and create the default service. For details about how to deploy a version to the default service, see Deploying multiple service applications.

Too Many Versions (403)

App Engine has a limit on the number of deployed versions of your application. These differ for free applications and deployed applications. You can use the Cloud Console to delete an older version and then upload your latest code. You do not have permission to modify this app (403)

This can occur when the account that you are authenticated as does not have permission to deploy to the application ID that is specified in your command or in your appengine-web.xml. Check your application ID is accurate and matches the value of your Cloud Console project ID. Next, check the project permissions in the console and verify that your account is listed with a sufficient permission level to allow for deploying apps. If the account permission and project ID appear correct, you can try to force a reauthentication of your SDK by removing the .appcfg_oauth2_tokens file from your home directory and retry the deployment commands.

What's next