Notice: Over the next few months, we're reorganizing the App Engine documentation site to make it easier to find content and better align with the rest of Google Cloud products. The same content will be available, but the navigation will now match the rest of the Cloud products.

App Engine Maven Plugin (gcloud CLI-based) Goals and Parameters

After you add the gcloud CLI-based App Engine Maven plugin to your project, the following App Engine-specific Maven goals are available:

Goal Description
appengine:cloudSdkLogin Sets the global gcloud CLI state for account.
appengine:deploy Stages and deploys an application to App Engine.
appengine:deployAll Stages and deploys an application with all of its valid yaml configurations simultaneously to App Engine.
appengine:deployCron Stages and deploys a cron.yaml configuration file to App Engine.
appengine:deployDispatch Stages and deploys a dispatch.yaml configuration file to App Engine.
appengine:deployDos Stages and deploys a dos.yaml configuration file to App Engine.
appengine:deployIndex Stages and deploys an index.yaml configuration file to App Engine.
appengine:deployQueue Stages and deploys a queue.yaml configuration file to App Engine.
appengine:help Displays help information on the App Engine Maven plugin.
appengine:run Runs the App Engine development server. When the server is running, it continuously checks to determine whether appengine-web.xml has changed. If it has, the server reloads the application. You do not need to stop and restart your application because of changes to appengine-web.xml.
appengine:stage Generates an application directory for deployment.
appengine:start Starts running the App Engine devserver asynchronously and then returns to the command line. When this goal runs, the behavior is the same as the run goal except that Maven continues processing goals and exits after the server is up and running.
appengine:stop Stops a running App Engine web development server.

For more information on how to set up and use Maven, see Using Maven.

Goal parameters

Each goal has associated parameters that you can use. You can specify these settings in the pom.xml or in the command line.

To configure these settings in the pom.xml, add the parameter name in the <configuration> section.

The following example splits JAR files, stops the previously running version, and specifies the gcloud CLI path:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.4.3</version>
     <configuration>
       <stage.enableJarSplitting>true</stage.enableJarSplitting>
       <deploy.stopPreviousVersion>true</deploy.stopPreviousVersion>
       <cloudSdkHome>/usr/foo/path/to/cloudsdk</cloudSdkHome>
     </configuration>
  </plugin>
</plugins>

Alternatively, to configure these settings in the command line, follow the pattern -D[USER_PROPERTY]=[PARAMETER_VALUE].

The following example specifies a directory to stage your application to:

mvn appengine:stage -Dapp.stage.stagingDirectory=[YOUR_STAGING_DIRECTORY]

See the following sections for a list of the parameters that are available for each goal.

If you want to skip all appengine:goal executions, set the skip parameter to true.

appengine:deploy

Stages and deploys an application to App Engine.

You can use the following parameters, some of which correspond to gcloud app deploy command line flags:

Parameter Description Plugin configuration Command line configuration
appEngineDirectory Location of .yaml configuration files (cron, index, etc) from which configuration specific deployments (appengineDeployCron, etc) will deploy from. For standard applications, your .xml configuration files are converted during staging to .yaml and placed in target/appengine-staging/WEB-INF/appengine-generated. deploy.appEngineDirectory app.deploy.appEngineDirectory
bucket The Google Cloud Storage bucket used to stage files associated with the deployment. If this argument is not specified, the application's default bucket is used. deploy.bucket app.deploy.bucket
cloudSdkHome Optional parameter to configure the location of the gcloud CLI. If this property is not specified, then the plugin automatically downloads the gcloud CLI. cloudSdkHome cloudSdkHome
cloudSdkVersion Optional parameter to specify the desired gcloud CLI version. cloudSdkVersion cloudSdkVersion
compileEncoding The character encoding to use when compiling JSPs. Applies to the App Engine standard environment only. stage.compileEncoding app.stage.compileEncoding
deleteJsps Deletes the JSP source files after compilation. Applies to the App Engine standard environment only. stage.deleteJsps app.stage.deleteJsps
disableJarJsps Disable adding the classes generated from JSPs. Applies to the App Engine standard environment only. stage.disableJarJsps app.stage.disableJarJsps
dockerBuild Perform a hosted (remote) or local (local) Docker build. To perform a local build, you must have your local docker environment configured correctly. Default is a hosted build. deploy.dockerBuild app.deploy.dockerBuild
dockerfile The location of the dockerfile to use for App Engine Standard applications running on the flexible environment. Applies to the App Engine standard environment only. stage.dockerfile app.stage.dockerfile
enableJarClasses Jar the WEB-INF/classes content. Applies to the App Engine standard environment only. stage.enableJarClasses app.stage.enableJarClasses
enableJarSplitting Split JAR files larger than 10 MB into smaller fragments. Applies to the App Engine standard environment only. stage.enableJarSplitting app.stage.enableJarSplitting
enableQuickstart Use Jetty quickstart to process servlet annotations. Applies to the App Engine standard environment only. stage.enableQuickstart app.stage.enableQuickstart
force Force deploying, overriding any previous in-progress deployments to this version. deploy.force app.deploy.force
imageUrl Deploy with a specific Docker image. Docker URL must be from one of the valid Google Container Registry hostnames. deploy.imageUrl app.deploy.imageUrl
jarSplittingExcludes Exclude files that match the list of comma separated SUFFIXES from all JAR files. Applies to the App Engine standard environment only. stage.jarSplittingExcludes app.stage.jarSplittingExcludes
projectId The Google Cloud Platform project name to use for this invocation. You must specify a projectId or you can set GCLOUD_CONFIG to use the project set in your gcloud config state. deploy.projectId app.deploy.projectId
promote Promote the deployed version to receive all traffic. Default is True. deploy.promote app.deploy.promote
server The App Engine server to connect to. Typically, you do not need to change this value. deploy.server app.deploy.server
sourceDirectory Required. The location of the compiled web application files, or the exploded WAR. This is used as the source for staging. Applies to the App Engine standard environment only. Default is ${project.build.directory}/${project.build.finalName}. stage.sourceDirectory app.stage.sourceDirectory
stagingDirectory Required. The directory to which to stage the application. Default is ${project.build.directory}/appengine-staging. stage.stagingDirectory app.stage.stagingDirectory
stopPreviousVersion Stop the previously running version when deploying a new version that receives all traffic. deploy.stopPreviousVersion app.deploy.stopPreviousVersion
version The version of the app that will be created or replaced by this deployment. If you do not specify a version, one will be generated for you. deploy.version app.deploy.version

appengine:help

Displays help information about the App Engine Maven plugin.

To display parameter details, call:

mvn appengine:help -Ddetail=true -Dgoal=[GOAL_NAME]

You can use the following parameters:

Parameter Description User property
detail If true, display all settable properties for each goal. Default is False. detail
goal The name of the goal for which to show help. If unspecified, all goals will be displayed. goal
indentSize The number of spaces per indentation level. Should be a positive number. Default is 2. indentSize
lineLength The maximum length of a display line. Should be a positive number. Default is 80. lineLength

appengine:run

Runs the App Engine development web server. When the server is running, it continuously checks to determine whether appengine-web.xml has changed. If it has, the server reloads the application. This means that you do not need to stop and restart your application because of changes to appengine-web.xml.

You can use the following parameters, some of which correspond to the local development server command line flags:

Property Description Plugin configuration Command line configuration
automaticRestart Restart instances automatically when web application files (resources or class files) are changed. To configure Maven to put the compiled class files in the correct directory of the web app application, you must change the Maven outputDirectory setting: 
<build>
  <outputDirectory>
    target/${project.artifactId}-${project.version}/WEB-INF/classes
  </outputDirectory>
  ...
<plugins>
...
 devserver.automaticRestart app.devserver.automaticRestart
environment A map of environment variables to send to the local development server. Example: 
<environment>
  <key1>value1</key1>
  <key2>value2</key2>
</environment>
devserver.environment app.devserver.environment
jvmFlags Additional arguments to pass to the java command when launching an instance of the app. May be specified more than once. Example: 
<jvmFlags>
  <jvmFlag>-Xmx1024m</jvmFlag>
  <jvmFlag>-Xms256m</jvmFlag>
</jvmFlags>
devserver.jvmFlags app.devserver.jvmFlags
host Host name to which application services should bind. Default is localhost. devserver.host app.devserver.host
port Lowest port to which application services should bind. Default is 8080. devserver.port app.devserver.port
serverVersion Server version to launch, options are "1" and "2-alpha". Default is "1". devserver.serverVersion app.devserver.serverVersion
services Required. Path(s) to a directory containing a directory containing WEB-INF/web.xml. Default is build/exploded-app. devserver.services app.devserver.services

appengine:stage

Generates an application directory for deployment. The stage phase is automatically called before the appengine:deploy goal. This phase is in charge of:

  • Compiling the web application JSPs to servlet classes
  • Parsing all annotated servlets and generating a Jetty quickstart web.xml (only if web.xml is configured to use version 3.1 of the servlet specification.)
  • Optionally putting the compiled classes in a jar
  • Generating a complete app.yaml from the following files: appengine-web.xml, web.xml, annotated servlets
  • Copying all web application static files (html, css, js, images, etc) to a __static__/ directory which is then deployed as static files configured in app.yaml

The staging directory can be used to inspect what is being deployed and can be used as is for the gcloud app deploy command.

You can use the following parameters:

Parameter Description Plugin configuration Command line configuration
cloudSdkHome Optional parameter to configure the location of the gcloud CLI. If this property is not specified, then the plugin automatically downloads the gcloud CLI. cloudSdkHome cloudSdkHome
cloudSdkVersion Optional parameter to specify the desired gcloud CLI version. cloudSdkVersion cloudSdkVersion
compileEncoding The character encoding to use when compiling JSPs. Applies to the App Engine standard environment only. stage.compileEncoding app.stage.compileEncoding
deleteJsps Deletes the JSP source files after compilation. Applies to the App Engine standard environment only. stage.deleteJsps app.stage.deleteJsps
dockerfile The location of the dockerfile to use for App Engine Standard applications running on the flexible environment. Applies to the App Engine standard environment only. stage.dockerfile app.stage.dockerfile
enableJarClasses Jar the WEB-INF/classes content. Applies to the App Engine standard environment only. stage.enableJarClasses app.stage.enableJarClasses
enableJarSplitting Split JAR files larger than 10 MB into smaller fragments. Applies to the App Engine standard environment only. stage.enableJarSplitting app.stage.enableJarSplitting
enableQuickstart Use Jetty quickstart to process servlet annotations. Applies to the App Engine standard environment only. stage.enableQuickstart app.stage.enableQuickstart
jarSplittingExcludes Exclude files that match the list of comma separated SUFFIXES from all JAR files. Applies to the App Engine standard environment only. stage.jarSplittingExcludes app.stage.jarSplittingExcludes
sourceDirectory Required. The location of the compiled web application files, or the exploded WAR. This is used as the source for staging. Applies to the App Engine standard environment only. Default is ${project.build.directory}/${project.build.finalName}. stage.sourceDirectory app.stage.sourceDirectory
stagingDirectory Required. The directory to which to stage the application. Default is ${project.build.directory}/appengine-staging stage.stagingDirectory app.stage.stagingDirectory

appengine:start

Starts running the App Engine development web server asynchronously and then returns to the command line. When this goal runs, the behavior is the same as the run goal except that Maven continues processing goals and exits after the server is up and running.

You can use the following parameters:

Property Description Plugin configuration Command line configuration
environment A map of environment variables to send to the local development server. Example: 
<environment>
  <key1>value1</key1>
  <key2>value2</key2>
</environment>
devserver.environment app.devserver.environment
jvmFlags Additional arguments to pass to the java command when launching an instance of the app. May be specified more than once. Example: 
<jvmFlags>
  <jvmFlag>-Xmx1024m</jvmFlag>
  <jvmFlag>-Xms256m</jvmFlag>
</jvmFlags>
devserver.jvmFlags app.devserver.jvmFlags
host Host name to which application services should bind. Default is localhost. devserver.host app.devserver.host
port Lowest port to which application services should bind. Default is 8080. devserver.port app.devserver.port
serverVersion Server version to launch, options are "1" and "2-alpha". Default is "1". devserver.serverVersion app.devserver.serverVersion
services Required. Path(s) to a directory containing a directory containing WEB-INF/web.xml. Default is build/exploded-app. devserver.services app.devserver.services
startSuccessTimeout Amount of time in seconds to wait for the Dev App Server to start in the background (when using appengineStart). devserver.startSuccessTimeout app.devserver.startSuccessTimeout

appengine:stop

Stops a running App Engine web development server.

You can use the following parameters:

Parameter Description Plugin configuration Command line configuration
host Host name to which the admin server should bind. Default is localhost devserver.adminHost app.devserver.adminHost
port Port to which the admin server should bind. Default is 8000. devserver.adminPort app.devserver.adminPort
cloudSdkHome Optional parameter to configure the location of the gcloud CLI. If this property is not specified, then the plugin automatically downloads the gcloud CLI. cloudSdkHome cloudSdkHome

Troubleshooting upload errors

If you use the deploy goal, your deployment attempt might fail with a message similar to this one: 404 Not Found This application does not exist (app_id=u'your-app-ID'). This error will occur if you have multiple Google accounts and are using the wrong account to perform the update.

To solve this issue, try changing the authorized user with gcloud auth login.