Using Apache Maven

Apache Maven is a software project management and comprehension tool. It is capable of building WAR files for deployment into App Engine. The App Engine team provides both a plugin and Maven Archetypes for the purpose of speeding up development.

Requirements

To use Maven with Managed VMs, you need to do the following:

1. Download and install Maven if you don't have it installed. Version 3.1 or later is required.

2. Install the Google Cloud SDK on your machine. The new Maven plugin goals will not download it automatically on build. Make sure you install an up-to-date version (Beta or later) that has the App Engine Managed VM components installed.

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

   gcloud components update app-engine-java
   

4. You must use Java 7. If you don't have Java 7, Download and install it. For App Engine Managed VMs images, it is possible to use Java 8 with some customization.

5. Set your JAVA_HOME environment variable. If you are a bash user, the following considerations apply:

   • For a typical Linux installation, add a line similar to the following to your .bashrc file:

     export JAVA_HOME=/usr/local/tools/java/jdk1.7.0_45.jdk
     

6. If you use Mac OS X and the default Terminal app, your shell session doesn't load .bashrc by default. So you may need to add a line similar to the following to your .bash_profile:

       [ -r ~/.bashrc ] && source ~/.bashrc
   

7. If you use Mac OS X but don't use the default terminal app, for example, you use a terminal management app such as tmux, you may need to add a line similar to the following line to your .bashrc file:

       export JAVA_HOME=$(/usr/libexec/java_home -v1.7)
   

8. If you want to start with a Java Managed VM sample code and tutorial, you can use the GitHub project: https://github.com/GoogleCloudPlatform/appengine-java-vm-guestbook-extras

Adding the Cloud SDK App Engine Maven plugin to an existing Maven project

To add the Cloud SDK 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>gcloud-maven-plugin</artifactId>
   <version>2.0.9.72.v20150804</version>
</plugin>

Compile and build your project using Maven

To build an Java App Engine Web Application using Maven with its pom.xml file:

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

2. Invoke Maven as follows:

   
   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: Mon Jul 14 14:50:06 PST 2014
    Final Memory: 24M/213M
   
   

4. Optionally, run and test the application locally using the Cloud SDK development server, as described in the next section.

Run and test your app with the Cloud SDK development server

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

To run your app in the development server:

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

   mvn clean install
   

2. Run your app by changing directory to the top level of your project (for example, to myapp) and invoking Maven as follows:

   $ mvn gcloud:run
   

3. Wait for the 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 in the Windows/Linux terminal window where you started it, or CMD+C on the Mac.

App Engine Maven plugin goals for the Cloud SDK

The App Engine Maven plugin goals have been extended to work with a local Cloud SDK installation that enable Managed VMs development and deployment. These goals are listed in the following sections.

Development server goals

These are the Cloud SDK App Engine development server goals:

Available parameters for all gcloud:* goals:

Available parameters, corresponding to gcloud app run command line flags:

The following example shows how to use some of these settings:

  <plugin>
    <groupId>com.google.appengine</groupId>
    <artifactId>gcloud-maven-plugin</artifactId>
    <version>>2.0.9.72.v20150804</version>
    <configuration>
      <gcloud_directory>/usr/foo/private/google-cloud-sdk</gcloud_directory>
      <verbosity>debug</verbosity>
      <version>specific_version</version>
      <set_default>true</set_default>
      <log_level>info</log_level>
      <max_module_instances>2</max_module_instances>
    </configuration>
  </plugin>

Application deployment goal

You can deploy an App Engine Application via the goal gcloud:deploy.

    $ mvn gcloud:deploy

Available parameters, corresponding to gcloud app deploy command line flags:

Application management goals

The application and project management goals are listed in the following table:

Available parameters corresponding to gcloud app modules command line flags:

Configuration elements override via the command line interface

Instead of editing the pom.xml with the desired configuration, you can define all the configuration parameters in the mvn command line, following the simple pattern -Dgcloud.PARAM_NAME=PARAM_VALUE. For example:

  # To start the development server with debug flag:
  $ mvn gcloud:run -Dgcloud.verbosity=debug
  # To start the development server listening to 0.0.0.0 so it can be accessed outside of localhost:
  $ mvn gcloud:run -Dgcloud.host=0.0.0.0:8081
  # To specify a non default Cloud SDK installation directory:
  $ mvn gcloud:run -Dgcloud.gcloud_directory=YOUR_OWN_SPECIFIC_INSTALLATION_PATH
  # To specify the project ID and version at deployment time:
  $ mvn gcloud:deploy -Dgcloud.gcloud_project=myproject -Dgcloud.version=myversion

Enterprise Archive (EAR) support

You can use the Cloud SDK Maven plugin on App Engine projects of type war and ear.