Set up a local development environment for Temporal and Java

~10 minutesHands-on setupBeginner

You'll need a Java Development Kit (JDK), the Temporal Java SDK, and a build tool such as Apache Maven or Gradle.

Install the Java JDK

If you haven't done so already, install a JDK. Either download a copy directly from Oracle or select an OpenJDK distribution from your preferred vendor.

Check the version of your current JDK installation by executing java --version at a command prompt. These Java tutorials were developed and tested with Java 21, but they should work with JDKs version 8 or higher.

Add Temporal Java SDK dependencies

The Java tutorials use Apache Maven to manage dependencies and build applications. You can also use Gradle or other build automation tools.

Follow these steps to configure Maven or Gradle for Temporal.

Maven
Gradle

To install Apache Maven, download a copy and follow the instructions at Apache.org.

Add the following dependencies to your Maven Project Object Model (POM) configuration file (pom.xml) to compile, build, test, and run a Temporal Application in Java.

<dependencies>
  <!--
    Temporal dependencies needed to compile, build,
    test, and run Temporal's Java SDK
  -->

  <!--
    SDK
  -->
  <dependency>
    <groupId>io.temporal</groupId>
    <artifactId>temporal-sdk</artifactId>
    <version>1.31.0</version>
  </dependency>

  <dependency>
    <!--
      Testing
    -->
    <groupId>io.temporal</groupId>
    <artifactId>temporal-testing</artifactId>
    <version>1.31.0</version>
    <scope>test</scope>
  </dependency>
</dependencies>

The Gradle build tool is bundled with IntelliJ IDEA. To download and install it separately, follow the instructions at Gradle.org.

Add the following lines to build.gradle, your Gradle configuration file, so it works with the Temporal SDK:

implementation 'io.temporal:temporal-sdk:1.31.0'
testImplementation 'io.temporal:temporal-testing:1.31.0'

Next, you'll configure a local Temporal Service for development.

Set up a local Temporal Service for development with Temporal CLI

The fastest way to get a development version of the Temporal Service running on your local machine is to use Temporal CLI.

Temporal CLI is a tool for interacting with the Temporal Service from the command-line interface. It includes a self-contained distribution of the Temporal Service and Web UI which you can use for local development.

Install Temporal CLI on your local machine using the following instructions for your platform.

macOS
Windows
Linux

You can install the latest version with Homebrew using the following command:

brew install temporal

To install Temporal CLI on Windows, download the version for your architecture:

Once you've downloaded the file, extract the downloaded archive and add the temporal.exe binary to your PATH.

To install Temporal CLI, download the version for your architecture:

Once you've downloaded the file, extract the downloaded archive and add the temporal binary to your PATH by copying it to a directory like /usr/local/bin.

Once you've installed Temporal CLI and added it to your PATH, open a new Terminal window and run the following command:

temporal server start-dev

This command starts a local Temporal Service. It starts the Web UI, creates the default Namespace, and uses an in-memory database.

The Temporal Service will be available on localhost:7233.
The Temporal Web UI will be available at http://localhost:8233.

Leave the local Temporal Service running as you work through tutorials and other projects. You can stop the Temporal Service at any time by pressing CTRL+C.

Change the Web UI port

The Temporal Web UI may be on a different port in some examples or tutorials. To change the port for the Web UI, use the --ui-port option when starting the server:

temporal server start-dev --ui-port 8080

The Temporal Web UI will now be available at http://localhost:8080.

The temporal server start-dev command uses an in-memory database, so stopping the server will erase all your Workflows and all your Task Queues. If you want to retain those between runs, start the server and specify a database filename using the --db-filename option, like this:

temporal server start-dev --db-filename your_temporal.db

When you stop and restart the Temporal Service and specify the same filename again, your Workflows and other information will be available.

Verify your setup

Before moving on, confirm everything works:

Temporal CLI is installed.
```
temporal --version
```
Returns the installed version (e.g. temporal version 1.x.x).
The local Temporal Service runs. Start it in a new terminal:
```
temporal server start-dev
```
You'll see the server start, with the Web UI listening on http://localhost:8233.
The Web UI loads. Open http://localhost:8233 in a browser - you should see the Temporal Web UI with no Workflows yet.

What's next?

Next step

Run your first Temporal application

Download a small Java app and watch Temporal recover from failure - in about 10 minutes.

Run your first app