<br />

<br />


[Gradle](https://docs.gradle.org/current/userguide/userguide.html)
is an open-source build automation tool focused on flexibility and performance.
App Engine provides a Gradle plugin that you can use to build and deploy
your app to App Engine.

> [!NOTE]
> **Note:** For information about other ways to build and deploy your app, see [Testing and deploying your app](https://docs.cloud.google.com/appengine/docs/standard/testing-and-deploying-your-app).

## Before you begin

1. [Install Java](http://www.oracle.com/technetwork/java/javase/downloads/index.html)

2. [Install Gradle](https://gradle.org/gradle-download/)

3. [Install git](https://git-scm.com/)

4. If you haven't already done so, follow the steps in this
   [guide](https://docs.cloud.google.com/appengine/docs/standard/setting-up-environment)
   to download the gcloud CLI, create your Google Cloud project, and
   initialize your App Engine app.

5. Install the gcloud CLI `app-engine-java` component:

       gcloud components install app-engine-java

## Create 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](https://github.com/GoogleCloudPlatform/java-docs-samples/blob/main/appengine-java21/helloworld/README.md).

To create a new project:

1. Create a new directory and navigate to it.

2. To initialize a new project:

   1. Run `gradle init`:

          gradle init --type java-application

      You'll be asked to answer questions:
      - Enter target Java version (min: 7, default: 21): 21
      - Select application structure: 1 for Single application project
      - Select build script DSL: 2 (for Groovy)
      - Select test framework: 1 (for JUnit 4)
      - Generate build using new APIs and behavior: no
   2. Create the `WEB-INF` folder:

          mkdir -p app/src/main/webapp/WEB-INF

   3. Create the `appengine` folder:

          mkdir -p app/src/main/appengine

3. Remove the stub files generated by `gradle init`:

       rm ./app/src/main/java/org/example/App.java ./app/src/test/java/org/example/AppTest.java

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


       apply plugin: 'java'
       apply plugin: 'war'

       buildscript {
           repositories {
               // gretty plugin is in Maven Central
               mavenCentral()
           }
           dependencies {
               classpath 'com.google.cloud.tools:appengine-gradle-plugin:2.8.1'
               classpath 'org.gretty:gretty:4.1.5'
           }
       }
       apply plugin: 'org.gretty'
       apply plugin: 'com.google.cloud.tools.appengine'

       repositories {
           mavenCentral()
       }

       appengine {
           deploy {   // deploy configuration
               stopPreviousVersion = true  // default - stop the current version
               promote = true              // default - & make this the current version
               projectId = 'GCLOUD_CONFIG'
               version = 'GCLOUD_CONFIG'
           }
       }

       sourceSets {
           // In Gradle 8, the default location is app/src/java, which does not match
           // Maven's directory structure.
           main.java.srcDirs = ['src/main/java']
           main.resources.srcDirs = ['src/main/resources', 'src/main/webapp']
           test.java.srcDirs = ['src/test/java']
       }

       dependencies {
           implementation 'com.google.appengine:appengine-api-1.0-sdk:2.0.30'
           implementation 'jakarta.servlet:jakarta.servlet-api:6.1.0'

           // Test Dependencies
           testImplementation 'com.google.appengine:appengine-testing:2.0.30'
           testImplementation 'com.google.appengine:appengine-api-stubs:2.0.30'
           testImplementation 'com.google.appengine:appengine-tools-sdk:2.0.30'

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

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


   - [`app/src/main/appengine/app.yaml`](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/configuring-your-app-with-app-yaml)

   - app/src/main/docker/Dockerfile (optional for [custom runtimes](https://docs.cloud.google.com/appengine/docs/flexible/custom-runtimes/build))
   - Java classes
   - Java [testing classes](https://docs.cloud.google.com/appengine/docs/legacy/standard/java/tools/localunittesting)

See [Set up your development environment](https://docs.cloud.google.com/appengine/docs/standard/setting-up-environment) for an
overview of a Java App Engine project.

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

   Alternatively, you can run Gradle without installing it by [using the Gradle wrapper](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/using-gradle#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:

   ```
   :prepareInplaceWebAppFolder
   :createInplaceWebAppFolder
   :compileJava
   :processResources UP-TO-DATE
   :classes
   :prepareInplaceWebAppClasses
   :prepareInplaceWebApp
   :jettyRun
   17:40:05 INFO  Jetty 9.2.15.v20160210 started and listening on port 8080
   17:40:05 INFO   runs at:
   17:40:05 INFO    http://localhost:8080/
   ```
5. See your app running at [`http://localhost:8080`](http://localhost:8080).

To learn more about the [Gretty plugin](https://github.com/akhikhl/gretty),
see [Gretty Configuration](http://akhikhl.github.io/gretty-doc/Gretty-configuration.html)
and [Gretty tasks](http://akhikhl.github.io/gretty-doc/Gretty-tasks).

## Deploy 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](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/gradle-reference).


## Use the Gradle wrapper

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

### Linux/macOS

1. Change to the sample code directory.

2. Run gradlew:

       ./gradlew jettyRun

### Windows

1. Change to the sample code directory.

2. Run gradlew:

       ./gradlew.bat jettyRun

Additional information on Gradle can be found in

[App Engine Gradle Tasks and Properties](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/gradle-reference).


## What's next

- Explore the plugin code and report issues on [GitHub](https://github.com/GoogleCloudPlatform/app-gradle-plugin).
- Learn how to specify properties for tasks by referring to [App Engine Gradle Tasks and Properties](https://docs.cloud.google.com/appengine/docs/standard/java-gen2/gradle-reference).