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 or newer.
Maven downloads the Java libraries from the App Engine SDK. You can use Maven to test your app locally and deploy it to App Engine.
Before you start
- Use the Google Cloud Console to create and set up your Cloud project:
Go to App Engine- Select or create a new Cloud project.
- 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.
- If you don't have Java, download, install, and configure it.
- Set the Java compiler flags in your project's
pom.xml
to specify Java 8 bytecode.Java 8 - You must have Maven 3.5 or newer installed. To see if Maven
3.5 or newer is installed, run:
mvn -v
- If you don't have Maven 3.5 or newer installed:
- You don't need to install the Cloud SDK because the plugin automatically installs the SDK when required.
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>2.2.0</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 | appengine-skeleton-archetype |
Generates a new, empty App Engine project ready for your own classes and resources, but with required files and directories. |
App Engine app | appengine-standard-archetype |
Generates a basic Java application for the App Engine standard environment. |
App Engine app | appengine-flexible-archetype |
Generates a basic Java application for the App Engine flexible environment. |
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. |
Creating a new App Engine app
The following procedure describes how to use the appengine-skeleton-archetype
to create an App Engine application.
To use App Engine Maven archetypes to create an App Engine app:
Change to the directory where you want to build the project.
Invoke the following Maven command:
mvn archetype:generate -Dappengine-version=1.9.59 -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, andapplication-id
to the ID of your Cloud project.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
.Select the most recent version from the displayed list of available archetype versions by accepting the default.
When prompted to
Define value for property 'groupId'
, supply the desired namespace for your app; for example,com.mycompany.myapp
.When prompted to
Define value for property 'artifactId'
, supply the project name; for example,myapp
.When prompted to
Define value for property 'version'
, accept the default value.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.When prompted to confirm your choices, accept the default value (
Y
).Wait for the project to finish generating. then change directories to the new project directory, for example
myapp/
.Build the project by invoking
mvn clean package
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] --------------------------------------------------
If you created a new, empty app using the
appengine-skeleton-archetype
artifact: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 apom.xml
file, thesrc/main/java
subdirectory, and thesrc/main/webapp/WEB-INF
subdirectory:- 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
- Add your own application Java classes to
Create your application Java classes and add them to
src/main/java/...
. For more information, see Getting Started.Add the UI that you want to provide to your app users. For more information, see Adding Application Code and UI.
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.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.
Managing, testing, and deploying a Maven project
Compiling and building your project
To build an application created with the Maven App Engine archetypes:
Change to the main directory for your project.
Invoke Maven:
mvn clean package
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
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.
To test your App Engine app:
If you haven't already done so, build your app:
mvn clean package
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
Use your browser to visit
http://localhost:8080/
to access your app.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>2.2.0</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 package appengine:deploy -Dapp.deploy.projectId=PROJECT_ID
Replace PROJECT_ID with the ID of your 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 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
- Explore the App Engine Maven plugin code and report issues on GitHub.
- Learn how to specify parameters for goals by referring to App Engine Maven Goals and Parameters.