# What Is the Purpose of the War Directory in Jenkins? A Technical Breakdown

> Explore the Jenkins war directory and its purpose in assembling the jenkins.war file. Understand how it bundles the web UI, launcher, and servlet container for deployment.

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

---

**The `war` directory in the Jenkins source repository contains the Maven module that assembles the `jenkins.war` file, bundling the web UI assets, executable launcher, and embedded Winstone servlet container into a single self-contained deployable archive.**

The `war` directory sits at the heart of the `jenkinsci/jenkins` repository, serving as the build module responsible for producing the executable web application. Understanding the purpose of the war directory in Jenkins is essential for developers who want to compile from source, customize deployments, or troubleshoot the bootstrap process.

## Core Responsibilities of the War Module

### Packaging the Web Application

The [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) file declares this module as a Maven WAR project using `<packaging>war</packaging>`. This configuration instructs Maven to aggregate compiled classes, static resources, and dependencies into the standard Java Web Application Archive format recognized by servlet containers.

### Bundling Static Resources

All HTML, CSS, JavaScript, images, and localization files reside under `war/src/main/webapp/`. This directory structure mirrors the WAR's internal layout, with assets like `war/src/main/webapp/images/title.svg` and the `war/src/main/webapp/scripts/` folder packaged directly into the archive root for runtime access.

### Embedding the Executable Launcher

The [`war/src/main/java/executable/Main.java`](https://github.com/jenkinsci/jenkins/blob/main/war/src/main/java/executable/Main.java) class provides the entry point when running `java -jar jenkins.war`. According to the Jenkins source code, this launcher extracts the embedded Winstone servlet container, validates the Java version, and initializes the web server without requiring an external Tomcat or Jetty installation.

### Including Required Plugins and Libraries

The Maven configuration in [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) copies core plugins into `WEB-INF/plugins` and detached plugins into `WEB-INF/detached-plugins`. The Winstone JAR is also embedded within the archive, ensuring the servlet container travels with the application.

### Configuring the Servlet Container

The `jetty-ee9-maven-plugin` in [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) defines server settings, login services, and system properties. Configuration files like `war/src/main/resources/realm.properties` provide default security realms for the embedded container, while [`war/src/main/webapp/WEB-INF/web.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/src/main/webapp/WEB-INF/web.xml) supplies the minimal servlet descriptor.

## Key Source Files in the War Directory

- **[`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml)**: Defines the module build, dependencies, and WAR packaging configuration.
- **[`war/src/main/java/executable/Main.java`](https://github.com/jenkinsci/jenkins/blob/main/war/src/main/java/executable/Main.java)**: Entry point for the executable WAR; handles Winstone extraction and server startup.
- **[`war/src/main/webapp/WEB-INF/web.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/src/main/webapp/WEB-INF/web.xml)**: Minimal servlet descriptor defining display name and version information.
- **`war/src/main/webapp/scripts/`**: JavaScript utilities powering UI behaviors like table sorting.
- **`war/src/main/webapp/images/`**: SVG and PNG assets for icons and status indicators.
- **`war/src/main/resources/realm.properties`**: Default login configuration for the embedded Jetty/Winstone container.
- **[`war/src/test/java/executable/MainTest.java`](https://github.com/jenkinsci/jenkins/blob/main/war/src/test/java/executable/MainTest.java)**: Unit tests validating the launcher argument handling and version logic.

## Building and Running Jenkins from the War Source

To build the WAR artifact from the `war` directory:

```bash

# From the repository root

mvn clean install -DskipTests

# Run the built artifact

java -jar war/target/jenkins.war --httpPort=8080

```

When executed, the `java -jar` command invokes the `executable.Main` class specified in the WAR's MANIFEST file. This bootstrap sequence extracts Winstone into a temporary directory and delegates control to the embedded servlet container.

Accessing bundled resources at runtime:

```java
// Load a static image from within the WAR
InputStream logo = getClass().getResourceAsStream("/images/title.svg");

```

## Summary

- The `war` directory is a Maven module that produces the `jenkins.war` deployable artifact.
- It bundles static web assets, the executable launcher (`executable/Main`), and the Winstone servlet container.
- Configuration files like `realm.properties` and [`web.xml`](https://github.com/jenkinsci/jenkins/blob/main/web.xml) define runtime behavior for the embedded server.
- Building from source requires Maven and produces a self-running JAR via `java -jar`.

## Frequently Asked Questions

### What does WAR stand for in Jenkins?

WAR stands for Web Application Archive, the standard Java EE format for packaging web applications. In Jenkins, the WAR file is self-executable because it contains the `executable.Main` class and an embedded Winstone servlet container, allowing you to run `java -jar jenkins.war` without deploying to an external server.

### How do I run Jenkins directly from the war directory source?

First build the artifact using `mvn clean install -DskipTests` from the repository root. Then execute `java -jar war/target/jenkins.war --httpPort=8080`. The `executable.Main` class in [`war/src/main/java/executable/Main.java`](https://github.com/jenkinsci/jenkins/blob/main/war/src/main/java/executable/Main.java) handles the startup sequence by extracting the embedded container and launching the web server.

### What servlet container does Jenkins use?

Jenkins embeds Winstone, a lightweight servlet container built on Jetty. The [`war/pom.xml`](https://github.com/jenkinsci/jenkins/blob/main/war/pom.xml) configures the `jetty-ee9-maven-plugin` to include this dependency, and the `executable.Main` bootstrap class extracts and initializes Winstone at runtime when you execute the WAR file.

### Where are Jenkins UI assets stored in the source tree?

Static assets including JavaScript, CSS, and images are located under `war/src/main/webapp/`. Subdirectories like `war/src/main/webapp/scripts/` and `war/src/main/webapp/images/` contain the frontend resources that power the Jenkins user interface, packaged directly into the WAR during the Maven build process.