Google Cloud Platform
Hide
Java
Write Feedback

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.

        gcloud components update app

  3. Make sure you are logged in to you Google Cloud account:

        gcloud auth login

  4. Configure the project you wish to work with:

        gcloud config set project <your_project_id>

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

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

    • 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

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

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

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

You are now ready to run and test the application locally using the Cloud SDK development server, as described in the next section.

Adding the App Engine Maven plugin to an existing Maven project

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>gcloud-maven-plugin</artifactId>
   <version>1.9.17a</version>
</plugin>

Run and deploy 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 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 package

  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 terminal window where you started it.

To deploy your app to the Google Cloud:

    $ mvn gcloud:deploy

After a while, you should be able to access it from the http://YOUR_APP_ID.appspot.com URL. The first deployment of Managed VMs Docker images takes a while as what is uploaded is the full content of the Docker image.

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:

Goal Description
gcloud:run Runs the Beta Cloud SDK App Engine development server for Managed VMs applications as well as non Managed VMs application.
gcloud:run_start Performs an asynchronous start for the devserver and then returns to the command line. When this goal runs, the behavior is the same as the run goal except that Maven continues processing goals and exits after the server is up and running.
gcloud:stop Stops the development server. Available only if you started the development server with gcloud:start.

Available parameters for all gcloud:* goals:

Parameter Description
gcloud_directory The location of the Cloud SDK to use from Maven. (Default is ~/google-cloud-sdk)

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

Parameter Description
admin_host The host and port on which to start the admin server (in the format host:port)
allow_skipped_files Make files specified in the app.yaml "skip_files" or "static" clauses readable by the application.
api_host The host and port on which to start the API server for the dev server (in the format host:port). Not needed when using boot2docker.
appidentity_email_address Email address associated with a service account that has a downloadable key. May be None for no local application identity.
appidentity_private_key_path Path to private key file associated with service account (.pem format). Must be set if appidentity_email_address is set.
auth_domain Name of the authorization domain to use
blobstore_path Path to directory used to store blob contents (defaults to a subdirectory of storage_path if not set)
clear_datastore Clear the datastore on startup
datastore_consistency_policy The policy to apply when deciding whether a datastore write should appear in global queries (default is "time")
datastore_path Path to a file used to store datastore contents (defaults to a file in storage_path if not set)
default_gcs_bucket_name Default Google Cloud Storage bucket name
enable_mvm_logs Enable logs collection and display in local Dev Admin Console for Managed VM modules. This will start extra log Docker containers.
enable_sendmail Use the "sendmail" tool to transmit e-mail sent using the Mail API (ignored if smtp_host is set)
host The host and port on which to start the local web server (in the format host:port)
jvm_flag Additional arguments to pass to the java command when launching an instance of the app. May be specified more than once. Example: <jvm_flag><param>-Xmx1024m</param> <param>-Xms256m</param></jvm_flag> Note: This is not for Java Managed VMs applications. Please use a Dockerfile for that.
log_level The minimum verbosity of logs from your app that will be displayed in the terminal. (debug, info, warning, critical, error) Defaults to current verbosity setting.
logs_path Path to a file used to store request logs (defaults to a file in storage_path if not set)
max_module_instances The maximum number of runtime instances that can be started for a particular module - the value can be an integer, in which case all modules are limited to that number of instances, or a comma-separated list of module:max_instances, e.g. default:5,backend:3
php_executable_path The full path to the PHP executable to use to run your PHP module.
python_startup_script The script to run at the startup of new Python runtime instances (useful for tools such as debuggers)
require_indexes Generate an error on datastore queries that require a composite index not found in index.yaml
show_mail_body Logs the contents of e-mails sent using the Mail API
smtp_allow_tls Allow TLS to be used when the SMTP server announces TLS support (ignored if --smtp-host is not set)
smtp_host The host and port of an SMTP server to use to transmit e-mail sent using the Mail API, in the format host:port
smtp_password Password to use when connecting to the SMTP server specified with smtp_host
smtp_user Username to use when connecting to the SMTP server specified with smtp_host
storage_path The default location for storing application data. Can be overridden for specific kinds of data using datastore_path, blobstore-path, and/or logs_path
use_mtime_file_watcher Use mtime polling for detecting source code changes - useful if modifying code from a remote machine using a distributed file system

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

  <plugin>
    <groupId>com.google.appengine</groupId>
    <artifactId>gcloud-maven-plugin</artifactId>
    <version>1.9.17a</version>
    <configuration>
      <gcloud_directory>/usr/foo/private/google-cloud-sdk</gcloud_directory>
      <enable_mvm_logs>true</enable_mvm_logs>
      <gcloud_verbosity>debug</gcloud_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.

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

Parameter Description
compile-encoding Set the encoding to be used when compiling Java source files (default "UTF-8")
delete_jsps Delete the JSP source files after compilation
disable_jar_jsps Do not jar the classes generated from JSPs
enable_jar_classes Jar the WEB-INF/classes content
enable_jar_splitting Split large jar files (> 32M) into smaller fragments
env_vars Environment variable overrides for your app.
force Force deploying, overriding any previous in-progress deployments to this version.
jar_splitting_excludes When enable-jar-splitting is specified and jar_splitting_excludes specifies a comma-separated list of suffixes, a file in a jar whose name ends with one of the suffixes will not be included in the split jar fragments
no_symlinks Do not use symbolic links when making the temporary (staging) directory used in uploading Java apps
retain_upload_dir Do not delete temporary (staging) directory used in uploading Java apps
server The App Engine server to connect to. You will not typically need to change this value.
set_default Set the deployed version to be the default serving version.
version The version of the app that will be created or replaced by this deployment.

Application management goals

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

Goal Description
gcloud:module_cancel_deployment Cancel (rollback) the current deployment. Useful when the deployment has been interrupted for some reason.
gcloud:module_delete Delete the module as defined in appengine-web.xml.
gcloud:module_set_default Set as default the module.
gcloud:module_set_managed_by Configure the specified backend.
gcloud:module_start Start the module as defined in appengine-web.xml.
gcloud:module_stop Stop the module as defined in appengine-web.xml.

Available parameters corresponding to gcloud app modules command line flags:

Parameter Description
server The App Engine server to connect to. You will not typically need to change this value.
version The version of the app that will be created or replaced by this deployment.

Configuration elements override via the command line interface

Instead of editing the pom.xml with the desired configuration, all the configuration parameters can be overridden 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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License, and code samples are licensed under the Apache 2.0 License. For details, see our Site Policies.