# How to Set Up Jenkins for Local Development and Testing

> Set up Jenkins for local development and testing by cloning the repository, building the WAR file with Maven, and launching the instance with Jetty. Get your local Jenkins environment running fast.

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

---

**To set up Jenkins for local development, clone the jenkinsci/jenkins repository, build the WAR file with Maven using the quick-build profile, and launch the development instance with the Jetty plugin using specific JVM `--add-opens` flags.**

Jenkins is an open-source automation server written in Java and built with Apache Maven. Setting up a local development environment allows you to compile the `jenkins.war`, run a live instance via the embedded Jetty server, and contribute changes to the core codebase. The official [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) and [`README.md`](https://github.com/jenkinsci/jenkins/blob/main/README.md) files in the jenkinsci/jenkins repository provide the canonical instructions for preparing your toolchain.

## Prerequisites for Jenkins Development

Before building Jenkins locally, you must install a supported **JDK** (version 21 or 25) and **Apache Maven** (version 3.9.6 or newer). These requirements are defined in the root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) and enforced by the Maven toolchain. Ensure both `java` and `mvn` commands are available on your system `PATH` before proceeding.

## Building the Jenkins WAR File

The first step is to clone the repository and compile the web application archive. The `war` module contains the [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) that assembles `jenkins.war`, while the root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml) orchestrates the multi-module build.

Run the following command to perform a quick build that skips tests:

```bash
git clone https://github.com/jenkinsci/jenkins.git
cd jenkins
mvn -am -pl war,bom -Pquick-build clean install

```

This produces the deployable artifact at `war/target/jenkins.war`. The `-Pquick-build` profile accelerates the process by excluding the test suite, which is useful for rapid iteration during development.

## Launching a Local Development Instance

Jenkins provides a Maven profile that starts a Jetty server for local testing. Because Jenkins accesses internal JDK modules, you must pass specific `--add-opens` arguments via `MAVEN_OPTS` to avoid reflection-related runtime errors.

Start the development server with:

```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

```

The instance will be available at `http://localhost:8080/jenkins`. This configuration reads the compiled classes from the `war` module and serves them using the Jetty plugin configuration defined in [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml).

## Developing Frontend Assets with Hot Reload

If you are modifying JavaScript or CSS in the `war` module, you can enable hot-reload by running the webpack dev server separately. First ensure **Yarn** is enabled via Corepack, then install the node modules:

```bash
corepack enable
yarn install

```

In one terminal, start Jenkins while skipping the frontend asset processing:

```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 -Dskip.yarn

```

In a second terminal, start the frontend watch mode:

```bash
yarn start

```

This setup proxies requests to the Jenkins backend while providing live reloading for changes to the UI assets located in the `war` module.

## Debugging with a Remote JVM Debugger

To attach an IDE debugger, export `MAVEN_OPTS` with the Java Debug Wire Protocol (JDWP) agent alongside the required `--add-opens` flags:

```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

```

You can then attach your debugger to `localhost:5005`. This configuration is essential for stepping through code in the `core/src/main/java` directory or analyzing the startup behavior of the Jenkins automation server.

## Summary

- **Prerequisites:** Install JDK 21 or 25 and Maven 3.9.6+ as specified 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:** Launch with `mvn -pl war jetty:run` after setting `MAVEN_OPTS` with the three required `--add-opens` flags for JDK access.
- **Frontend:** Use `yarn start` in the `war` module for hot-reload, running Jenkins with `-Dskip.yarn`.
- **Debug:** Add `-agentlib:jdwp` to `MAVEN_OPTS` and attach to port 5005.

## Frequently Asked Questions

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

According to the [`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md) in the jenkinsci/jenkins repository, you must use **JDK 21 or 25** to build and run the current master branch. These versions are enforced by the Maven toolchain plugin defined in the root [`pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/pom.xml).

### Why are the `--add-opens` JVM arguments required when running Jenkins locally?

Jenkins uses deep reflection to access internal classes within the `java.base` module (specifically `java.lang`, `java.io`, and `java.util`). Without these `--add-opens` flags passed via `MAVEN_OPTS`, the modular JDK throws `IllegalAccessException` errors during startup, preventing the development instance from initializing.

### Can I skip building the frontend assets if I only work on Java code?

Yes. When running `mvn -pl war jetty:run`, you can append `-Dskip.yarn` to bypass the Yarn build phases. This accelerates startup if you are only modifying Java source files in the `core` module and do not need to process JavaScript or CSS changes.

### Where is the official documentation for contributing to Jenkins?

The definitive guide is located in the repository's **[`CONTRIBUTING.md`](https://github.com/jenkinsci/jenkins/blob/main/CONTRIBUTING.md)** file. It covers prerequisite installation, IDE-specific hints, and detailed instructions for building and launching development instances, complementing the high-level overview found in [`README.md`](https://github.com/jenkinsci/jenkins/blob/main/README.md).