Using Gradle and the App Engine Plugin

You can use Gradle, a flexible build automation system that is declarative and is used to automate build, testing, publishing, and deployment. This page explains how to use Gradle with an App Engine project in the standard environment.

Before you begin

Install and configure the following prerequisites:

Setting up and validating your Google Cloud project

You need to set up your Google Cloud project and install the gcloud CLI:

  1. Use the Google Cloud console to create and set up your Google Cloud project:

    Go to App Engine

    1. Select or create a new Google Cloud project.
    2. Follow the prompts to ensure that an App Engine application exists and billing is enabled:
      1. 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.
      2. Follow the prompts to create a new billing account or select an existing account.
    3. The Dashboard opens after your App Engine application has been created and billing has been enabled in your project.

  2. You don't need to install the gcloud CLI because the plugin automatically installs the SDK when required.

Creating a new Gradle project

You can create a new Gradle project from scratch using the shell. Alternatively, to try out the plugin, you can download, run locally, and deploy the hello world project.

  1. Create and enter a new directory.

  2. To initialize a new project:

    gradle init --type java-library;
mkdir -p src/main/webapp/WEB-INF;
rm src/main/java/Library.java src/test/java/LibraryTest.java

  3. Add the following to your build.gradle file to add App Engine Gradle tasks, Maven repositories, the App Engine Gradle plugin, dependencies, and task configuration:

    buildscript {    // Configuration for building
  repositories {
    jcenter()    // Bintray's repository - a fast Maven Central mirror & more
    mavenCentral()
  }
  dependencies {
    classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.5.0' // If a newer version is available, use it
  }
}

repositories {   // repositories for Jar's you access in your code
  maven {
    url 'https://oss.sonatype.org/content/repositories/snapshots' // SNAPSHOT repository (if needed)
  }
  mavenCentral()
  jcenter()
}

apply plugin: 'java'                              // standard Java tasks
apply plugin: 'war'                               // standard Web Archive plugin
apply plugin: 'com.google.cloud.tools.appengine'  // App Engine tasks

dependencies {
  implementation 'com.google.appengine:appengine-api-1.0-sdk:+'  // Latest App Engine Api's
  providedCompile 'javax.servlet:javax.servlet-api:3.1.0'

  implementation 'jstl:jstl:1.2'

// Add your dependencies here.
//  implementation 'com.google.cloud:google-cloud:+'   // Latest Cloud API's http://googlecloudplatform.github.io/google-cloud-java

  testImplementation 'junit:junit:4.13.2'
  testImplementation 'com.google.truth:truth:1.1.5'
  testImplementation 'org.mockito:mockito-core:4.11.0'

  testImplementation 'com.google.appengine:appengine-testing:+'
  testImplementation 'com.google.appengine:appengine-api-stubs:+'
  testImplementation 'com.google.appengine:appengine-tools-sdk:+'
}

// Always run unit tests
appengineDeploy.dependsOn test
appengineStage.dependsOn test

appengine {  // App Engine tasks configuration
  deploy {   // deploy configuration
    projectId = System.getenv('GOOGLE_CLOUD_PROJECT')
    version = '1'
  }
}

test {
  useJUnit()
  testLogging.showStandardStreams = true
  beforeTest { descriptor ->
     logger.lifecycle("test: " + descriptor + "  Running")
  }

  onOutput { descriptor, event ->
     logger.lifecycle("test: " + descriptor + ": " + event.message )
  }
  afterTest { descriptor, result ->
    logger.lifecycle("test: " + descriptor + ": " + result )
  }
}

group   = "com.example.appenginej8"        // Generated output GroupId
version = "1.0-SNAPSHOT"       // Version in generated output

sourceCompatibility = 1.8     // App Engine Flexible uses Java 8
targetCompatibility = 1.8     // App Engine Flexible uses Java 8

  4. You also need to add the following files to your project, using a text editor or integrated development environment (IDE):

See Configuration files for an overview of a Java App Engine project.

Downloading the Hello World app

  1. Clone the Hello World sample app repository to your local machine:

    git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git

    Alternatively, you can download the sample as a zip file and extract it.

  2. Change to the directory that contains the sample code:

    cd java-docs-samples/appengine-java8/helloworld

Testing your application with the development server

  1. To access Google resources from your project when running locally, set the application default credentials by running:

    gcloud auth application-default login

  2. Change to the root of your application directory.

  3. During the development phase, you can run and test your application at any time in the development server by invoking Gradle:

    gradle appengineRun

    Alternatively, you can run Gradle without installing it by using the Gradle wrapper.

  4. Wait for the server to start. The server is started with your application running when you see a message similar to this:

    :compileJava
:processResources NO-SOURCE
:classes
:war
:explodeWar
:assemble
:appengineRun
2018-06-05 22:50:46.231:INFO::main: Logging initialized @321ms
Jun 06, 2018 2:50:49 AM com.google.appengine.tools.development.AbstractModule startup
INFO: Module instance default is running at http://localhost:8080/
Jun 06, 2018 2:50:49 AM com.google.appengine.tools.development.AbstractModule startup
INFO: The admin console is running at http://localhost:8080/_ah/admin
Jun 05, 2018 10:50:49 PM com.google.appengine.tools.development.DevAppServerImpl doStart
INFO: Dev App Server is now running

  5. See your app running at http://127.0.0.1:8080.

Debugging on the development server

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

    appengine {
      run {
        jvmFlags = ['-Xdebug', '-Xrunjdwp:transport=dt_socket,server=y,suspend=y,address=5005']
      }
    }

Enable hot reload of the application

Hot Reloading is the ability to update one or more classes in an application that is currently running without stopping the environment. To enable hot reload:

  • You must tell the local server to scan for changes:

    appengine {
  run {
    automaticRestart = true
  }
}

  • While your app is running, run the explodeWar task to copy the changes into the exploded app directly and propagate your changes into the running application.

Deploying your application

To deploy your application:

gradle appengineDeploy

The appengineDeploy task and all other Gradle tasks have associated properties that you can use. For a complete list of tasks and properties, refer to App Engine Gradle Tasks and Properties.

Using the Gradle wrapper

Gradle provides a mechanism to download and run the required version of Gradle without installation:

Linux/macOS

./gradlew appengineRun

Windows

gradlew.bat appengineRun

Additional information on Gradle can be found in App Engine Gradle Tasks and Properties.

What's next