Using Apache Maven and the App Engine Plugin

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 WAR files for deployment into App Engine. Google provides a plugin and Maven Archetypes which are included with Maven 3.1 and greater.

When you use Maven, you don't need to download the Java libraries from the Google App Engine SDK. Maven does that for you. You can also use Maven to test your app locally and upload (deploy) it to production App Engine.

Setting up Maven

Configuring Java

  1. If you don't have Java, download, install and configure it.

  2. You can use Java 7 or Java 8, but you must use Java 7 bytecode level. If you are using Java 8, configure your app to target Java 7 in your project's pom.xml:

    <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>

Installing Maven 3.3.9+

To determine whether Maven is installed and which version you have, invoke the following command:

 mvn -v

If you don't have the proper version of Maven installed:

  1. Download Maven 3.3.9 or greater from the Maven website.
  2. Install Maven 3.3.9 or greater on your local machine.

Setting up and validating your Cloud Platform project

You need to set up your Cloud Platform project and install the App Engine SDK:

  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, you are prompted to select the region where you want your App Engine application located.
    3. The Dashboard opens after your App Engine application has been created in your project.
  2. Install the App Engine SDK for Java and add the directory to your PATH.

Using Maven

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

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

<plugin>
   <groupId>com.google.appengine</groupId>
   <artifactId>appengine-maven-plugin</artifactId>
   <version>1.9.49</version>
</plugin>

Choosing an 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 Version Description
App Engine app* guestbook-archetype 3.0.2-1.9.38 Generates the guestbook demo sample, complete and ready to run and test.
App Engine app* appengine-skeleton-archetype 2.0.2-1.9.25 Generates a new, empty App Engine project ready for your own classes and resources, but with required files and directories.
Cloud Endpoints API backend hello-endpoints-archetype 1.1.5-1.9.38 Generates a simple starter Cloud Endpoints backend API project, ready to build and run.
Cloud Endpoints API backend endpoints-skeleton-archetype 1.1.5-1.9.38 Generates a new, empty Cloud Endpoints backend API project ready for your own classes and resources, with required files and directories.

* App Engine app in this context means a regular App Engine app, not an app serving as a Cloud Endpoints backend API.

Creating a new project

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.

The following table shows how to use App Engine Maven archetypes to create an App Engine app or a Cloud Endpoints backend API. Click on the desired app type to see the instructions.

App Engine App

To create an App Engine App:

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

  2. Invoke the following Maven command:

         mvn archetype:generate -Dappengine-version=1.9.49 -Dapplication-id=your-app-id -Dfilter=com.google.appengine.archetypes:
    

    where -Dappengine-version is set to the most recent version of the App Engine SDK for Java, and application-id is set 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 version 3.0.2-1.9.38 (guestbook-archetype) or 2.0.2-1.9.25 (appengine-skeleton-archetype) from the displayed list of available archetype versions.

  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 or guestbook.

  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 guestbook/.

  11. Build the project by invoking

    mvn clean install
    
  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 the sample Guestbook demo app using the guestbook-archetype artifact:

    1. Test the application locally in the development server:

      mvn appengine:devserver
      

      Wait for the dev server to start up. When it finishes starting up, you will see a message similar to this:

       [INFO] INFO: Module instance default is running at http://localhost:8080/
       [INFO] Sep 15, 2014 11:44:19 AM com.google.appengine.tools.development.AbstractModule startup
       [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
       [INFO] Sep 15, 2014 11:44:19 AM com.google.appengine.tools.development.DevAppServerImpl doStart
       [INFO] INFO: Dev App Server is now running
      
    2. Visit the application at the default URL and port http://localhost:8080/ used by the development server. You will see the guestbook demo app.

    3. To shut down the app and the development server, press Control+C in the Windows/Linux terminal window you started it in, or CMD+C on the Mac.

  14. 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 is complete: 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

      • You'll add your own application Java classes to src/main/java/...
      • You'll configure your application using the file src/main/webapp/WEB-INF/appengine-web.xml
      • You'll 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.

Cloud Endpoints Backend API

To create a Cloud Endpoints backend API project:

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

  2. Invoke the following Maven command:

         mvn archetype:generate -Dappengine-version=1.9.49 -Dfilter=com.google.appengine.archetypes:
    

    where -Dappengine-version is set to the most recent version of the App Engine SDK for Java.

  3. If you want to create the complete, ready-to-run Hello Endpoints backend API, supply the number corresponding to hello-endpoints-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 endpoints-skeleton-archetype.

  4. Select version 1.1.5-1.9.38 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, com.mycompany.myapp. (For the Hello Endpoints sample backend API, supply the value com.google.appengine.samples.helloendpoints.)

  6. When prompted to Define value for property 'artifactId', supply the project name; for example, myapp. (For the Hello Endpoints sample, 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 install
    
  12. Wait for the project to build. When the project successfully finishes you will see a message similar to this one:

    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 14.846s
    [INFO] Finished at: Tue Jun 03 09:43:09 PDT 2014
    [INFO] Final Memory: 24M/331M
    
  13. If you created the sample Hello Endpoints sample backend API:

    1. Test the application locally in the development server:

      mvn appengine:devserver
      

      Wait for the dev server to start up. When it finishes starting up, you will see a message similar to this one:

       [INFO] INFO: Module instance default is running at http://localhost:8080/
       [INFO] Jun 03, 2014 9:44:47 AM com.google.appengine.tools.development.AbstractModule startup
       [INFO] INFO: The admin console is running at http://localhost:8080/_ah/admin
       [INFO] Jun 03, 2014 9:44:47 AM com.google.appengine.tools.development.DevAppServerImpl doStart
       [INFO] INFO: Dev App Server is now running
      
    2. Visit the URL http://localhost:8080 to send requests to the backend API

  14. If you created a new, empty app:

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

      Maven Project Layout

      YourFirstAPI.java is a starter file for your own API. (You aren't required to use this name.)

    2. Add your classes as desired.

Managing a Maven project

Compiling and building your project

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

  1. Change directory to the main directory for your project, for example, guestbook/
  2. Invoke Maven:

    mvn clean install
    
  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: Thur Jul 04 14:50:06 PST 2014
     Final Memory: 24M/213M
    
  4. Optionally, test the application using the following procedure.

Testing your app with the development server

During the development phase, you can run and test your app at any time in the development server by invoking the App Engine Maven plugin. The procedure varies slightly depending on the artifact used to create the project, so click on the appropriate tab below:

App Engine App

To test your app:

  1. If you haven't already done so, build your app (mvn clean install).

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

    mvn appengine:devserver
    

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

     Aug 24, 2014 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
     INFO: The server is running at http://localhost:8080/
     Aug 24, 2014 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
     INFO: The admin console is running at http://localhost:8080/_ah/admin
    
  3. 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 in the Windows/Linux terminal window where you started it, or CMD+C on the Mac.

Cloud Endpoints Backend API

To test your app:

  1. If you haven't already done so, build your app (mvn clean install).

  2. Change directory to your project's main directory /myapp) and invoke Maven:

    mvn appengine:devserver
    

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

     Jul 04, 2014 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
     INFO: The server is running at http://localhost:8080/
     Jul 04, 2013 2:56:42 PM com.google.appengine.tools.development.DevAppServerImpl start
     INFO: The admin console is running at http://localhost:8080/_ah/admin
    
  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 app and the development server by pressing Control+C in the Windows/Linux terminal window where you started it, or CMD+C on the Mac.

Specifying a port for local testing

When you run your app in the local development server, the default port is 8080. You can change this default by modifying the plugin entry for appengine-maven-plugin (or adding it if it doesn't exist). For example, we specify port and address in the following <plugin> entry within <plugins> inside the main app directory pom.xml file (myapp/pom.xml):

    <plugin>
         <groupId>com.google.appengine</groupId>
         <artifactId>appengine-maven-plugin</artifactId>
         <version>1.9.49</version>
         <configuration>
             <enableJarClasses>false</enableJarClasses>
             <port>8181</port>
             <address>0.0.0.0</address>
         </configuration>
    </plugin>

Notice that the <port> sets the port here to 8181 as shown, and the address 0.0.0.0 is specified, which means the development server will listen to requests coming in from the local network.

Deploying your app

See the Deploying your app guide.

Reference: Available goals

Once the App Engine Maven plugin is added to the project's pom.xml file, several App Engine-specific Maven goals are available. To see all of the available goals, invoke the command:

    mvn help:describe -Dplugin=appengine

The App Engine Maven plugin goals can be categorized as devserver goals, app and project management goals, and Endpoints goals.

Development server goals

These are the development server goals:

appengine:devserver

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 does a hot reload of the application. This means that you do not need to stop and restart your application because of changes to appengine-web.xml. The following parameters are available: