Run and debug an App Engine Standard app locally in Cloud Code for IntelliJ

Caution: Cloud Code supports up to Java 8 runtimes. As of January 31, 2024, Java 8 support for App Engine has ended, and will be deprecated on January 31, 2026. As a result, Cloud Code disables App Engine by default. To enable App Engine in your IDE, navigate to Settings > Google Cloud Code > App Engine. Due to the upcoming deprecation of App Engine, we don't recommend creating new App Engine projects. For more information about App Engine deprecations, see Feature deprecations. For more information about the runtime support schedule for App Engine, see Runtime support schedule.

Prior to deploying your application to App Engine, you can run and debug your App Engine standard application locally. This document describes how to configure the IDE for local run and debug from within IntelliJ IDEA.

Note: The following IDEs support this feature:

• IntelliJ IDEA - Ultimate
• IntelliJ IDEA - Community

Note: For the App Engine standard environment, only Java applications using Java 8 runtime are supported on Cloud Code.

Before you begin

• Ensure your application is an App Engine standard project that contains an appengine-web.xml file

• To access the Cloud Client Libraries locally, complete the Adding Cloud Client Libraries to Your Maven Projects procedures.

Note: Run configurations for local run and debug are only available in IntelliJ Ultimate Edition. If you are using Community Edition, you can follow the debugging your application locally on Community Edition instructions to use the Maven or Gradle plugins for your local run.

Running your application locally

If you're using IntelliJ IDEA Ultimate Edition, you can run an App Engine application locally by following these instructions:

1. Select File > Open to open the project you want to run.

2. Browse to the directory containing your project.

3. Select Tools > Cloud Code > App Engine Run on a local App Engine Standard dev server.

The project takes a moment to build.

Editing the run configuration

Configure the server

You can edit the run configuration for your local server:

1. Select Run > Edit Configurations.

2. From the Run/Debug Configurations dialog, update configuration settings as needed. Some common settings include:

   • Artifact to deploy.
   • App Engine Host.
   • App Engine Port.

Add environment variables

If needed, add environment variables to your configuration.

1. Select the Startup/Connection tab.

2. Select Run.

3. Select the Pass environment variables checkbox.

4. Add the necessary variables.

5. Select Debug.

6. Select the Pass environment variables checkbox.

7. Add the necessary variables.

   

8. When finished, click OK.

Stopping the server

To stop the Dev App Server, choose Run > Stop 'Google App Engine Standard Local Server'.

Debugging the application

You can use the run configuration you previously created to run your application in debug mode as follows:

1. Select Run > Debug.

2. In the dialog, click Google App Engine Standard Local Server.

3. After the project builds, you can set breakpoints to debug your app.

Debugging your application locally on Community Edition

IntelliJ Community Edition does not provide built-in support for running local Java servlet-based applications. To debug your application locally using IntelliJ Community Edition, configure your project to use the Maven or Gradle plugin.

Maven

Configuring your project using the Maven plugin

1. Add the App Engine Maven plugin to your project's pom.xml file.

2. Configure debugging on a development server.

3. Create Run/Debug configuration for Maven.

   

   1. Select Run > Edit Configurations.

   2. Click + Add New Configuration.

   3. Select Maven.

   4. In the Command line field, enter appengine:run.

   5. Click OK.

4. Create a remote debug configuration.

   

   1. Select Run > Edit Configurations.

   2. Click + Add New Configuration.

   3. Select Remote.

   4. Ensure that the port number is the same as the port you configured in your Maven App Engine plugin configuration. Port 5005 is the default.

   5. In the Before launch section, click + Add.

   6. Select Run Another Configuration.

   7. Select the run configuration for your Maven project.

   8. Click OK.

5. To debug your application locally:

   1. Select Run > Debug.

   2. Select your remote debug configuration.

      

      You can now debug your application locally.

Gradle

Configuring your project using the Gradle plugin

1. Create a new Gradle project.

2. Configure debugging on a development server.

3. Create Run/Debug configuration for Gradle.

   

   1. Select Run > Edit Configurations.

   2. Click + Add New Configuration.

   3. Select Gradle.

   4. In the Gradle project field, select the module where you configured the appengine-gradle-plugin plugin.

   5. In the Tasks field, enter appengineRun.

   6. Click OK.

4. Create a remote debug configuration.

   

   1. Select Run > Edit Configurations.

   2. Click + Add New Configuration.

   3. Select Remote.

   4. Ensure that the port number is the same as the port you configured in your Gradle App Engine plugin configuration. Port 5005 is the default.

   5. In the Before launch section, click + Add.

   6. Select Run Another Configuration.

   7. Select the run configuration for your Gradle project.

   8. Click OK.

5. To debug your application locally:

   1. Select Run > Debug.

   2. Select your remote debug configuration.

      

      You can now debug your application locally.

   3. If the Attach Debugger link appears in the console log, click the link.

      Note: If the port you've chosen is blocked, configure a different port number (for example, 5009) in your Gradle App Engine plugin configuration and update the port number in the remote configuration to the same port number.

What's next

• Next, you can deploy your app to the App Engine standard environment.

Get support

To submit feedback or report an issue in your IntelliJ IDE, go to Tools > Cloud Code > Help / About > Submit feedback or report an issue to report an issue on GitHub.