Use Gradle and the App Engine plugin

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

Before you begin

Install Java
Install Gradle
Install git
If you haven't already done so, follow the steps in this guide to download the gcloud CLI, create your Google Cloud project, and initialize your App Engine app.

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 .

To create a new project:

Create a new directory and navigate to it.
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 
 
```

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

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' 
 }

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
- app/src/main/docker/Dockerfile (optional for custom runtimes )
- Java classes
- Java testing classes

See Set up your development environment for an overview of a Java App Engine project.

Testing your application with the development server

To access Google resources from your project when running locally, set the application default credentials by running:
```
  gcloud 
  
 auth 
  
 application 
 - 
 default 
  
 login 
 
```
Change to the root of your application directory.
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 .

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/

See your app running at http://localhost:8080 .

To learn more about the Gretty plugin , see Gretty Configuration and 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 .

Use the Gradle wrapper

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

Linux/macOS

Change to the sample code directory.
Run gradlew:
```
  . 
 / 
 gradlew 
  
 jettyRun 
 
```

Windows

Change to the sample code directory.

Run gradlew:

  . 
 / 
 gradlew 
 . 
 bat 
  
 jettyRun

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

What's next

Explore the plugin code and report issues on GitHub .
Learn how to specify properties for tasks by referring to App Engine Gradle Tasks and Properties .