Using Apache Maven and the App Engine Plugin (Cloud SDK-based)

This page explains how to manage an App Engine project using Apache Maven, a software project management and comprehension tool. It is capable of building Web Application Archive (WAR) files for deployment into App Engine. Google provides a plugin and Maven Archetypes that are supported by Maven 3.5 and greater.

Maven downloads the Java libraries from the Google App Engine SDK. You can use Maven to test your app locally and deploy it to App Engine.

Before you start

  1. Use the Google Cloud Platform Console to create and set up your Cloud Platform project:
    Go to App Engine
    1. Select or create a new Cloud Platform project.
    2. If you need to create an App Engine application for your project, follow the prompts to select the region where you want your App Engine application located.
  2. Download and install the Google Cloud SDK, then initialize the gcloud command line tool:
    Download the SDK

    If you already have the gcloud command line tool installed and want to set it to use a different Cloud Platform project ID than the one that you initialized it to, see Managing Cloud SDK Configurations.

    Note: Optionally, run gcloud auth application-default login to authorize your user account without creating a Cloud SDK configuration. You can also run gcloud auth activate-service-account --key-file=your_key.json if you want to use a service account. For more information, see Authorizing Cloud SDK Tools.

  3. Install the Cloud SDK app-engine-java component:
    gcloud components install app-engine-java

    Note: Make sure you have the latest version of the Cloud SDK for Java by periodically running gcloud components update.

  4. If you don't have Java, download, install, and configure it.
  5. Set the Java compiler flags in your project's pom.xml to specify Java 7 bytecode or Java 8 byte code. See the appropriate tab below for the settings. Note that the App Engine Java 7 runtime requires Java 7 bytecode.
    Java 7
    <properties>  <!-- App Engine Standard currently requires Java 7 -->
      <maven.compiler.target>1.7</maven.compiler.target>
      <maven.compiler.source>1.7</maven.compiler.source>
    </properties>
    Java 8
    <properties>
      <maven.compiler.source>1.8</maven.compiler.source>
      <maven.compiler.target>1.8</maven.compiler.target>
    </properties>
  6. You must have Maven 3.5 installed. Determine whether Maven 3.5 is installed by invoking the following command:
     mvn -v
  7. If you don't have the proper version of Maven installed:
    1. Download Maven 3.5 from the Maven website.
    2. Install Maven 3.5 on your local machine.

      Note: Linux users may need to download Maven instead of using apt-get install to install Maven 3.5.

Adding the App Engine Maven plugin to an existing project (optional)

To use the Google App Engine Maven plugin in an existing Maven project, add the following into the plugins section in the project pom.xml file:

<plugin>
   <groupId>com.google.cloud.tools</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.3.1</version>
</plugin>

Choosing an App Engine archetype

Maven Archetypes allow users to create Maven projects using templates that cover common scenarios. App Engine takes advantage of this Maven feature to provide some useful App Engine archetypes at Maven Central. Select an App Engine archetype appropriate for your app:

Application Type Artifact Description
App Engine app* guestbook-archetype Generates the guestbook demo sample, complete and ready to run and test.
App Engine app* appengine-skeleton-archetype Generates a new, empty App Engine project ready for your own classes and resources, but with required files and directories.
Endpoints Frameworks for App Engine endpoints-skeleton-archetype Generates a new, empty Endpoints Frameworks for App Engine backend API project ready for your own classes and resources, with required files and directories.
Endpoints Frameworks for App Engine hello-endpoints-archetype Generates a starter Endpoints Frameworks for App Engine backend API project, ready to build and run.

* App Engine app in this context means a regular App Engine app, not an app serving as an endpoint, using the Cloud Endpoints Frameworks.

Creating a new project using Maven

During project creation, Maven prompts you to supply groupId, artifactId, version, and the package for the project.

Term Meaning
groupId A namespace within Maven to keep track of your artifacts. When people consume your project in their own Maven Project, it will serve as an attribute of the dependency they will end up specifying.
artifactId The name of your project within Maven. It is also specified by consumers of your project when they depend on you in their own Maven projects.
version The initial Maven version you want to have your project generated with. It's a good idea to have version suffixed by -SNAPSHOT because this will provide support in the Maven release plugin for versions that are under development. For more information, see the Maven guide to using the release plugin.
package The Java package created during the generation.

App Engine skeleton

To use App Engine Maven archetypes to create an App Engine App:

  1. Change to the directory where you want to build the project.

  2. Invoke the following Maven command:

    mvn archetype:generate -Dappengine-version=1.9.54 -Dapplication-id=[YOUR-PROJECT-ID] -Dfilter=com.google.appengine.archetypes:
    

    Set -Dappengine-version to the most recent version of the App Engine SDK for Java, and application-id to the ID of your Cloud Platform project.

  3. If you want to create the complete, ready-to-run guestbook sample app, supply the number corresponding to com.google.appengine.archetypes:guestbook-archetype.

    If you want to create an empty project that contains the required directory structure and files, ready for your own classes, supply the number corresponding to com.google.appengine.archetypes:appengine-skeleton-archetype.

  4. Select the most recent version from the displayed list of available archetype versions by accepting the default.

  5. When prompted to Define value for property 'groupId', supply the desired namespace for your app; for example, com.mycompany.myapp.

  6. When prompted to Define value for property 'artifactId', supply the project name; for example, myapp.

  7. When prompted to Define value for property 'version', accept the default value.

  8. When prompted to Define value for property 'package', supply your preferred package name (or accept the default). The generated Java files will have the package name you specify here.

  9. When prompted to confirm your choices, accept the default value (Y).

  10. Wait for the project to finish generating. then change directories to the new project directory, for example myapp/.

  11. Build the project by invoking

        mvn clean package
    
  12. Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

        [INFO] --------------------------------------------------
        [INFO] BUILD SUCCESS
        [INFO] --------------------------------------------------
        [INFO] Total time: 1:16.656s
        [INFO] Finished at: 2016-08-04T16:18:24-07:00
        [INFO] Final Memory: 16M/228M
        [INFO] --------------------------------------------------
    
  13. If you created a new, empty app using the appengine-skeleton-archetype artifact:

    1. Before starting to code your own classes for the app, familiarize yourself with the basic project layout and the required project files: inside the directory where you created the project, you'll have a subdirectory named myapp, which contains a pom.xml file, the src/main/java subdirectory, and the src/main/webapp/WEB-INF subdirectory:

      Maven Project Layout

      • Add your own application Java classes to src/main/java/...
      • Configure your application using the file src/main/webapp/WEB-INF/appengine-web.xml
      • Configure your application deployment using the file src/main/webapp/WEB-INF/web.xml
    2. Create your application Java classes and add them to src/main/java/.../ For more information, see Getting Started

    3. Add the UI that you want to provide to your app users. For more information, see Adding Application Code and UI.

    4. The artifact you used to create the project has done the basic src/main/webapp/WEB-INF/appengine-web.xml configuration for you. However, for more advanced configuration, you may need to edit this file. For more information, see Configuring with appengine-web.xml.

    5. Edit the file src/main/webapp/WEB-INF/web.xml to map URLs to your app handlers, specify authentication, filters, and so forth. This is described in detail in The Deployment Descriptor.

Endpoints Frameworks for App Engine

This archetype provides an example of using plugins, including App Engine Maven plugin and Endpoints Frameworks Maven plugin.

This archetype generates an example Greetings API using the new Endpoints Frameworks for App Engine. It also acts as an example for migrating your older Endpoints Frameworks applications. This sample is a migrated version of prior versions of this archetype described here.

The README.md that's generated with the archetype provides information of where the migration occurred.

To create an Endpoints Frameworks for App Engine backend API archetype project:

  1. Change directory to a directory where you want to build the project.

  2. Invoke the following Maven command:

    mvn archetype:generate -Dgoogle-cloud-project=[YOUR-PROJECT-ID] -Dappengine-plugin=1.3.1 -Dendpoints-frameworks=2.0.7 -Dendpoints-plugin=1.0.0 --Dappengine-sdk=1.9.53 -Dfilter=com.google.appengine.archetypes:
    

    where -Dgoogle-cloud-project is set to your project id, -Dappengine-plugin is set to the most recent version of the App Engine Maven plugin, -Dendpoints-frameworks is set to the most recent version of the Endpoints Frameworks for App Engine for Maven dependencies, and -Dendpoints-plugin is set to the most recent version of the Endpoints Frameworks for App Engine Maven plugin.

  3. Supply the number corresponding to hello-endpoints-archetype.

  4. Select the most recent version from the displayed list of available archetype versions.

  5. When prompted to Define value for property 'groupId', supply the namespace for your app; for example, supply the value com.example.helloendpoints.)

  6. When prompted to Define value for property 'artifactId', supply the project name; for example, supply the value helloendpoints.)

  7. When prompted to Define value for property 'version', accept the default value.

  8. When prompted to Define value for property 'package', accept the default value.

  9. When prompted to confirm your choices, accept the default value (Y).

  10. Wait for the project to finish generating. then change directories to the new project directory, for example helloendpoints/.

  11. Build the project by invoking

    mvn clean package
    
  12. Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 4.062 s
    [INFO] Finished at: 2017-02-28T00:28:03-08:00
    [INFO] Final Memory: 27M/485M
    [INFO] ------------------------------------------------------------------------
    
  13. To test locally and deploy project to Google App Engine standard environment, review Managing, testing, and deploying a Maven project.

  14. Additionally, you can generate Java client libraries for The Greeting API using the Endpoints Framework Maven Plugin:

    mvn endpoints-framework:clientLibs
    
  15. Looking into the example backend Greetings API:

    1. Familiarize yourself with the basic project layout shown here:

      Maven Project Layout

    2. README.md contains information about the generated example.

    3. Greetings.java contains an API definition for an example Greetings API.
    4. Constants.java contains constants used in by the example Greetings API.
    5. HelloGreeting.java contains a container for messages received and sent from the example Greetings API.
    6. index.html contains simple UI to call the backend Greetings API.
    7. base.js contains necessary Javascript for the UI to make backend requests.
    8. build.gradle once generated, the example also supports Gradle and more information about this functionality in the README.md.

Managing, testing, and deploying a Maven project

Compiling and building your project

To build an application created with the Maven App Engine archetypes:

  1. Change to the main directory for your project, for example, guestbook/.

  2. Invoke Maven:

    mvn clean package
    
  3. Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

    BUILD SUCCESS
     Total time: 10.724s
     Finished at: 2016-08-04T16:18:24-07:00
     Final Memory: 24M/213M
    
  4. Optionally, test the application using the following procedure.

Testing your application with the development server

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

Guestbook for App Engine

To test your app:

  1. If you haven't already done so, build your app:

    mvn clean package
    
  2. Change directory to the top level of your project (for example, to myapp) and invoke Maven:

    mvn appengine:run
    

    Wait for the server to start. When the server is completely started with your application running, you will see a message similar to this:

    [INFO] GCLOUD: INFO: Module instance default is running at http://localhost:44180/
    [INFO] GCLOUD: Jul 29, 2016 9:23:55 PM com.google.appengine.tools.development.AbstractModule startup
    [INFO] GCLOUD: INFO: The admin console is running at http://localhost:44180/_ah/admin
    [INFO] GCLOUD: Jul 29, 2016 9:23:55 PM com.google.appengine.tools.development.devappserver2.DevAppServer2Impl doStart
    [INFO] GCLOUD: INFO: Dev App Server is now running
    
  3. Use your browser to visit http://localhost:8080/ to access your app.

  4. Shut down the application and the development server by pressing Control-C.

Endpoints Frameworks for App Engine

To test your Endpoints Frameworks for App Engine app:

  1. If you haven't already done so, build your app:

    mvn clean package
    
  2. Run the example locally by running:

    mvn appengine:run
    

    Wait for the server to start. When the server is completely started with your application running, you will see a message similar to this:

    [INFO] GCLOUD: INFO ### devappserver2.py:764] Skipping SDK update check.
    [INFO] GCLOUD: INFO ### api_server.py:268] Starting API server at: http://localhost:34199
    [INFO] GCLOUD: INFO ### dispatcher.py:199] Starting module "default" running at: http://localhost:8080
    [INFO] GCLOUD: INFO ### admin_server.py:116] Starting admin server at: http://localhost:8000
    [INFO] GCLOUD: ### com.google.appengine.tools.development.SystemPropertiesManager setSystemProperties
    
  3. Use your browser to visit http://localhost:8080/ to access your app, or, alternatively, to test the API using the built-in Google API Explorer, visit http://localhost:8080/_ah/api/explorer.

  4. Shut down the application and the development server by pressing Control-C.

Specifying a port for local testing

When you run your application in the local development server, the default port is 8080. You can change this default by modifying the plugin entry for appengine-maven-plugin. For example, you can specify port and address in the pom.xml file of your application directory:

<plugins>
   <plugin>
     <groupId>com.google.cloud.tools</groupId>
     <artifactId>appengine-maven-plugin</artifactId>
     <version>1.3.1</version>
     <configuration>
       <devserver.host>0.0.0.0</devserver.host>
       <devserver.port>8181</devserver.port>
     </configuration>
  </plugin>
</plugins>

In this example, the <devserver.port> sets the port to 8181 instead of the default, and the address 0.0.0.0 is specified, which means the development server will listen to requests coming in from the local network.

The prefix devserver is optional; you can use <port>8181</port> instead.

Debugging on the development server

To debug a locally running application, set the jvmFlags in the plugin configuration to enable debugging on the underlying JVM, for example:

<configuration>
  <jvmFlags>
    <jvmFlag>-Xdebug</jvmFlag>
    <jvmFlag>-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005</jvmFlag>
  </jvmFlags>
</configuration>

Deploying your application

To deploy your application:

mvn appengine:deploy

The appengine:deploy goal and all other goals in the App Engine Maven plugin have associated parameters that you can use. For a complete list of goals and parameters, refer to App Engine Maven Plugin Goals and Parameters.

What's next

Monitor your resources on the go

Get the Google Cloud Console app to help you manage your projects.

Send feedback about...

App Engine standard environment for Java