Using Apache Maven and the App Engine Plugin

Apache Maven is a build automation tool for Java.

App Engine provides a Maven plugin that you can use to build and deploy your app to App Engine. The plugin does not support Enterprise Application Archive (EAR) projects.

Before you start

  1. Determine if Maven is installed and which version you have by running the following command:

    mvn -v

    If Maven is installed, a long string of information beginning with Apache Maven and followed by a version number such as 3.9.1 will display.

  2. If you don't have Maven 3.9.1 or newer installed:

    1. Download Maven 3.9.1 or newer.
    2. Install Maven 3.9.1 or newer.

  3. If you haven't already done so, follow the steps here to download the gcloud CLI, create your Google Cloud project, and initialize your App Engine app.

  4. Install the gcloud CLI app-engine-java component:

    gcloud components install app-engine-java

Adding the App Engine Maven plugin

To use the App Engine Maven plugin, add the following lines to the plugins section in your project's pom.xml file:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>2.8.1</version>
   </plugin>
   <plugin>
     <groupId>org.eclipse.jetty</groupId>
     <artifactId>jetty-maven-plugin</artifactId>
     <version>9.4.56.v20240826</version>
   </plugin>
</plugins>
 The App Engine plugin includes the Jetty Maven plugin, which you can use to test your application quickly without creating a WAR file.

Using the Jetty Maven plugin to test your app locally

During the development phase, you can run and test your app at any time in the development server by invoking the Jetty Maven plugin.

To run your app in the development server:

  1. Build your app if you haven't already done so:

    mvn package

  2. Change directory to the top level of your project (for example, to myapp), and run your app by invoking Maven:

    mvn jetty:run

  3. Wait for the server to start and use your browser to visit http://localhost:8080/ to access your app.

  4. Shut down the app and the development server by pressing Control+C.

Building and deploying your app

After you add the App Engine Maven plugin to your project's pom.xml file, you can use the following command to build deploy your app:

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

Replace PROJECT_ID with the ID of your Google 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.

The package goal builds and packages your app, and the appengine:deploy goal does the following:

  1. Generates a unique version ID for the new version of your app.

  2. Deploys the new version to App Engine.

  3. Routes all traffic to the new version.

Changing the deployment defaults

You can change the default deployment behavior by passing parameters in the appengine:deploy command. For example, the following command deploys the service defined in your pom.xml file to a specific Google Cloud project, assigns a custom version ID to the service, and turns off automatic traffic routing for the new version:

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

You can also use the appengine:deploy command to deploy configuration files, such as cron.yaml, dispatch.yaml, and index.yaml.

For more information, see the appengine:deploy reference .

What's next