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, you must have a GCP project and an App Engine application, see Managing Projects, Applications, and Billing for more information.
Setting up Maven (recommended)
To deploy your app using Maven, your project must be set up to use the Maven plugin for App Engine.
appcfg tool (alternative)
To deploy your app with the
appcfg tool, you must
download and install the
App Engine SDK for Java:
Deploying an app
To deploy your app to App Engine, you run Maven
(recommended) or the
command from within the root directory of your
Using Maven (recommended)
To deploy your app with Maven, run the following command from your project's top
level directory, where the
pom.xml file is located.
If you are using the App Engine SDK-based Maven plugin, use the command:
If you are using the Cloud SDK-based Maven plugin, use the command:
Using appcfg (alternative)
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/appcfg.sh [options] update [WAR_LOCATION]
If you are using an HTTP proxy, include the
--proxy argument to tell
its address. If you use a different proxy for HTTPS, then also include the
--proxy_https argument. See the
appcfg command line
for more information.
appengine-java-sdk\bin\appcfg.cmd --proxy=10.1.2.3 update [WAR_LOCATION]
Mac / Linux
./appengine-java-sdk/bin/appcfg.sh --proxy=10.1.2.3 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
However, many of our sample applications
appengine-web.xml file, as well as
Therefore, you must ensure that a GCP project ID is
specified for the application ID along with the version ID of your choice, for
appengine-java-sdk\bin\appcfg.cmd -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]
Mac / Linux
./appengine-java-sdk/bin/appcfg.sh -A [YOUR_PROJECT_ID] -V [YOUR_VERSION_ID] update [WAR_LOCATION]
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
defaultservice before you can create and deploy subsequent services.
You must specify the ID of your service in the
appengine-web.xmlconfiguration 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
You must specify all the corresponding
appengine-web.xmlconfiguration files in your deployment command to simultaneously deploy multiple services. The
defaultservice 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
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 Maven:
- Ensure that appengine-maven-plugin has been added to your parent
Run the following command:
appengine-java-sdk\bin\appcfg.cmd update [DEPLOYMENTS]
Mac / Linux
./appengine-java-sdk/bin/appcfg.sh update [DEPLOYMENTS]
[DEPLOYMENTS] is one or more configuration file's path and name. You
separate each configuration file that you specify with a single white space.
appengine-java-sdk\bin\appcfg.cmd update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]
Mac / Linux
./appengine-java-sdk/bin/appcfg.sh update [WAR_LOCATION] [SERVICE1_WAR_LOCATION] [MOD2_WAR_LOCATION]
You will receive verification via the command line as each service is successfully deployed.
To create or update the indexes that your app's use, you upload the
configuration file to Cloud Datastore. Indexes that don't exist yet are
created after that configuration file is uploaded.
It can take a while for Cloud 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:
index.xmlconfiguration file to Cloud Datastore before you deploy your version:
Build your indexes before migrating or splitting traffic to your version:
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 GCP project does not include the required
gcloud app deploycommand can fail when it tries to run the
gcloud app createcommand. 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
dev_appserver.shtools when you installed the App Engine SDK, you might need to specify the full directory path to run the tool, for example:
If you installed both the Google 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:
Tip: On Linux or Mac, you can run
which dev_appserver.pyto determine which SDK is first in your PATH.
 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
defaultservice. For details about how to deploy a version to the
defaultservice, 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 GCP 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 GCP 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_tokensfile from your home directory and retry the deployment commands.