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

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 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 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 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 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 supplies the minimal servlet descriptor.

Key Source Files in the War Directory

• war/pom.xml: Defines the module build, dependencies, and WAR packaging configuration.
• 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: 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: 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:

# 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:

// 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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}