# How to Set Up a Local Jenkins Development Environment: A Complete Guide

> Set up a local Jenkins development environment quickly. Clone the repo, install JDK and Maven, build the WAR, and launch Jenkins with simple Maven commands. Your complete guide.

- Repository: [Jenkins/jenkins](https://github.com/jenkinsci/jenkins)
- Tags: how-to-guide
- Published: 2026-07-30

---

**Clone the jenkinsci/jenkins repository, install JDK 21 or 25 with Maven 3.9.6+, build the WAR with `mvn -am -pl war,bom -Pquick-build clean install`, and launch with `mvn -pl war jetty:run` using the required `--add-opens` JVM flags.**

Setting up a local Jenkins development environment requires preparing a Java toolchain and leveraging the Maven-based build system defined in the repository root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml). Whether you are patching core functionality in `core/src/main/java` or tweaking the web UI, the process documented in [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) provides a reliable path to a runnable instance.

## Prerequisites for Jenkins Development

Before compiling the source, ensure your workstation meets the toolchain requirements specified in [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md). Jenkins is a Java application that requires specific JDK and Maven versions to build correctly.

Install the following:

- **JDK 21 or 25** – The root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) enforces these versions through the `maven-enforcer-plugin`. Ensure `JAVA_HOME` points to a compatible distribution.
- **Apache Maven 3.9.6 or newer** – Earlier versions may fail to resolve dependencies or handle the multi-module structure correctly.

Verify your installation:

```bash
java -version
mvn -version

```

## Building the Jenkins WAR

The build process generates `jenkins.war` in the `war/target/` directory. The root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) organizes the project into modules, including `war` and `bom` (Bill of Materials).

To compile without running tests, use the **quick-build** profile:

```bash

# Clone the repository

git clone https://github.com/jenkinsci/jenkins.git
cd jenkins

# Build the WAR and required modules

mvn -am -pl war,bom -Pquick-build clean install

```

The `-am` flag ensures upstream modules compile first, while `-pl war,bom` limits the build to the WAR and BOM artifacts. The resulting `war/target/jenkins.war` contains the standalone web application.

## Launching a Development Instance

You do not need an external servlet container for local testing. The [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) configures the **Jetty Maven Plugin**, allowing you to run Jenkins directly from the command line.

Jenkins requires access to internal JDK modules, so you must open specific Java packages using `--add-opens` flags. Set these via the `MAVEN_OPTS` environment variable:

```bash
MAVEN_OPTS='--add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run

```

Once the console shows "Jenkins is fully up and running," navigate to `http://localhost:8080/jenkins`. The instance runs with an empty `JENKINS_HOME` by default, creating a pristine environment for testing.

### Debugging with a Remote JVM

To attach an IDE debugger, modify `MAVEN_OPTS` to include the Java Debug Wire Protocol (JDWP) arguments:

```bash
MAVEN_OPTS='-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005 \
            --add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run

```

Configure your IDE to connect to `localhost:5005`. You can now set breakpoints in `core/src/main/java` and step through the Jenkins core logic.

## Developing Frontend Assets

The Jenkins UI relies on JavaScript and CSS assets built with **Yarn** and **webpack**. If you are modifying frontend code, running a dedicated dev server enables hot-reload functionality.

First, ensure Node.js and Yarn are available. The project recommends using **Corepack** to manage the Yarn version:

```bash
corepack enable
yarn install

```

Run Jenkins without processing frontend assets, then start the webpack dev server in a separate terminal:

```bash

# Terminal 1: Run Jenkins (skip yarn processing)

MAVEN_OPTS='--add-opens java.base/java.lang=ALL-UNNAMED \
            --add-opens java.base/java.io=ALL-UNNAMED \
            --add-opens java.base/java.util=ALL-UNNAMED' \
mvn -pl war jetty:run -Dskip.yarn

# Terminal 2: Start the webpack dev server

yarn start

```

The `yarn start` command watches for changes in the `war` module and pushes updates to the browser automatically. This workflow eliminates the need to restart the Java process for every CSS or JavaScript modification.

## Summary

- **Prerequisites**: Install JDK 21 or 25 and Maven 3.9.6+ as defined in the root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml).
- **Build**: Use `mvn -am -pl war,bom -Pquick-build clean install` to generate `war/target/jenkins.war`.
- **Run**: Execute `mvn -pl war jetty:run` with the three `--add-opens` flags in `MAVEN_OPTS` to satisfy JDK module access requirements.
- **Debug**: Add `-agentlib:jdwp` arguments to `MAVEN_OPTS` and attach your IDE to port 5005.
- **Frontend**: Use `yarn start` alongside `mvn jetty:run -Dskip.yarn` for hot-reload of UI assets.

## Frequently Asked Questions

### What JDK versions are officially supported for Jenkins development?

According to the [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) documentation and the root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) configuration, Jenkins supports **JDK 21 and JDK 25** for development. The build enforces these versions to ensure compatibility with modern Java features while maintaining the `--add-opens` requirements for internal module access.

### Can I run Jenkins development without installing Maven globally?

While the documentation assumes a local Maven installation, you can use the **Maven Wrapper** if included in the repository. However, the standard instructions in [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) reference Maven commands directly, so having Apache Maven 3.9.6 or newer installed globally provides the most straightforward experience when you set up a local Jenkins development environment.

### How do I skip the frontend build when I only changed Java code?

Pass the `-Dskip.yarn` property to the Maven Jetty plugin: `mvn -pl war jetty:run -Dskip.yarn`. This prevents the build from processing JavaScript assets, significantly speeding up startup times when you are only modifying Java classes in the `core` module.

### Where is the `jenkins.war` file located after building?

The compiled WAR file is generated at `war/target/jenkins.war` relative to the repository root. This path is configured in [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) and represents the deployable artifact containing the Jenkins core, plugins, and web resources.