Jenkins WAR file execution - Deep Dive

Overview - Jenkins WAR file execution

What is it?

Jenkins WAR file execution means running Jenkins as a standalone application using its WAR (Web Application Archive) file. This WAR file contains all the code and resources Jenkins needs to start a web server and provide its automation services. You can run this file directly with Java, without installing Jenkins through a package manager or container. This method is simple and useful for testing or small setups.

Why it matters

Running Jenkins from the WAR file lets you quickly start Jenkins anywhere with just Java installed, without complex setup. Without this, you would need to install Jenkins through system packages or containers, which can be slower or more complicated. This flexibility helps developers and teams try Jenkins fast, debug issues, or run Jenkins on systems where installation is restricted.

Where it fits

Before learning this, you should know basic Java commands and what Jenkins is used for. After mastering WAR file execution, you can learn about Jenkins installation methods, configuring Jenkins as a service, and advanced Jenkins pipeline setups.

Mental Model

Core Idea

Running the Jenkins WAR file is like launching a mini web server with Jenkins inside, using just Java and one file.

Think of it like...

Imagine the Jenkins WAR file as a portable coffee machine packed inside a suitcase. You just open the suitcase and plug it in anywhere with electricity (Java), and you get fresh coffee (Jenkins automation) without needing a full kitchen setup.

┌─────────────────────────────┐
│       Java Runtime          │
│  ┌───────────────────────┐ │
│  │   Jenkins WAR File     │ │
│  │  (Web Application)     │ │
│  └───────────────────────┘ │
│          Runs Jenkins        │
└─────────────────────────────┘

Build-Up - 6 Steps

1

Foundation

What is a WAR file in Jenkins

Concept: Introduce the WAR file as a packaged web app format Jenkins uses.

A WAR file is a single file that contains all the code, libraries, and resources needed to run a web application. Jenkins is distributed as a WAR file named jenkins.war. This file can be run by Java to start Jenkins without installing anything else.

Result

You understand that the Jenkins WAR file is a self-contained package to run Jenkins.

Knowing that Jenkins is packaged as a WAR file helps you see how it can run anywhere with Java, making it very portable.

2

Foundation

Running Jenkins WAR with Java command

Concept: Learn the basic command to start Jenkins from the WAR file.

To run Jenkins, open a terminal and type: java -jar jenkins.war This command tells Java to run the Jenkins WAR file as a program. Jenkins will start a web server on port 8080 by default.

Result

Jenkins starts running and you can access it in your browser at http://localhost:8080

Understanding this command is the key to running Jenkins quickly without installation.

3

Intermediate

Changing Jenkins port and options

🤔Before reading on: do you think Jenkins can run on any port you want by default? Commit to your answer.

Concept: Learn how to customize Jenkins startup options like port number.

You can change the port Jenkins listens on by adding --httpPort=PORT to the command. For example: java -jar jenkins.war --httpPort=9090 This starts Jenkins on port 9090 instead of 8080. You can also pass other options like --httpsPort or --prefix.

Result

Jenkins runs on the specified port, accessible at http://localhost:9090

Knowing how to customize Jenkins startup lets you avoid port conflicts and fit Jenkins into your environment.

4

Intermediate

Using Jenkins home directory for data

🤔Before reading on: do you think Jenkins stores its data inside the WAR file? Commit to your answer.

Concept: Understand where Jenkins keeps its configuration and build data when running from WAR.

Jenkins stores all its data in a directory called JENKINS_HOME. By default, this is ~/.jenkins on Linux/macOS or C:\Users\\.jenkins on Windows. You can change it by setting the environment variable JENKINS_HOME or passing --prefix. This directory holds jobs, plugins, and settings.

Result

Jenkins saves all your work and settings outside the WAR file, so your data persists between runs.

Knowing Jenkins home is separate from the WAR file helps you manage backups and upgrades safely.

5

Advanced

Running Jenkins WAR in background mode

🤔Before reading on: do you think Jenkins runs as a background service automatically when started with java -jar? Commit to your answer.

Concept: Learn how to run Jenkins WAR in the background or as a service.

By default, running java -jar jenkins.war runs Jenkins in the foreground, blocking your terminal. To run it in the background, you can use OS tools like: - Linux/macOS: java -jar jenkins.war & - Windows: start /b java -jar jenkins.war For production, you usually set up Jenkins as a system service using scripts or tools like systemd or NSSM.

Result

Jenkins runs continuously without tying up your terminal, suitable for real use.

Understanding how to run Jenkins in the background is essential for stable, long-term operation.

6

Expert

Security and performance considerations running WAR

🤔Before reading on: do you think running Jenkins WAR directly is always secure and performant for production? Commit to your answer.

Concept: Explore the limitations and risks of running Jenkins WAR directly in production.

Running Jenkins WAR directly is great for testing but has risks: - No automatic updates or service management - Runs with default settings, which may expose security risks - Performance tuning is limited Experts often run Jenkins behind a reverse proxy (like Nginx) with HTTPS, configure JVM options for memory, and use service managers for reliability.

Result

You understand that WAR execution is a starting point, not a full production setup.

Knowing the limits of WAR execution prevents security and stability issues in real environments.

Under the Hood

The Jenkins WAR file is a Java archive containing a web application packaged with all dependencies. When you run java -jar jenkins.war, the Java Virtual Machine (JVM) extracts and loads the web app into an embedded servlet container (Jetty). This container listens on a network port and serves Jenkins' web interface. Jenkins reads and writes configuration and job data to the JENKINS_HOME directory on disk. The JVM manages memory and threads for Jenkins processes.

Why designed this way?

Jenkins was designed as a WAR file to maximize portability and ease of use. Java WAR files are a standard way to package web apps, so Jenkins can run on any system with Java without complex installation. This design avoids OS-specific dependencies and lets users quickly start Jenkins anywhere. Alternatives like native installers or containers exist but require more setup or infrastructure.

┌───────────────────────────────┐
│        Java Virtual Machine    │
│  ┌─────────────────────────┐  │
│  │ Embedded Jetty Server    │  │
│  │  (inside Jenkins WAR)    │  │
│  └────────────┬────────────┘  │
│               │               │
│       Listens on port 8080    │
│               │               │
│  ┌────────────▼────────────┐  │
│  │  Jenkins Web Interface   │  │
│  └────────────┬────────────┘  │
│               │               │
│  Reads/Writes to JENKINS_HOME │
│  (config, jobs, plugins)      │
└───────────────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Does running Jenkins WAR file require a full Jenkins installation? Commit yes or no.

Common Belief: You must install Jenkins fully before running the WAR file.

Reality: The WAR file contains everything needed to run Jenkins; no separate installation is required.

Why it matters: Believing installation is needed can delay trying Jenkins or cause confusion about setup.

Quick: Is Jenkins data stored inside the WAR file? Commit yes or no.

Common Belief: All Jenkins data and configuration are inside the WAR file.

Reality: Jenkins stores data outside the WAR file in the JENKINS_HOME directory to keep data persistent.

Why it matters: Thinking data is inside the WAR can lead to data loss if the WAR is replaced or deleted.

Quick: Does running Jenkins WAR automatically secure Jenkins with HTTPS? Commit yes or no.

Common Belief: Jenkins WAR runs with HTTPS enabled by default for security.

Reality: By default, Jenkins WAR runs with HTTP on port 8080; HTTPS must be configured separately.

Why it matters: Assuming HTTPS is enabled can expose Jenkins to security risks on public networks.

Quick: Can you run multiple Jenkins WAR instances on the same port? Commit yes or no.

Common Belief: You can run multiple Jenkins WAR files on the same port simultaneously.

Reality: Only one process can listen on a port; running multiple Jenkins on the same port causes conflicts.

Why it matters: Ignoring port conflicts causes Jenkins startup failures and confusion.

Expert Zone

1

Jenkins WAR execution uses an embedded Jetty server, which can be tuned via JVM arguments for performance and memory management.

2

The JENKINS_HOME directory can be relocated or mounted from network storage, enabling Jenkins to run in containerized or cloud environments with persistent data.

3

Running Jenkins WAR directly lacks built-in service management; experts use OS-level service managers or container orchestration for reliability and automatic restarts.

When NOT to use

Running Jenkins WAR directly is not recommended for production environments requiring high availability, security, or scalability. Instead, use Jenkins installed as a system service, run inside containers with orchestration (like Kubernetes), or behind reverse proxies with HTTPS and authentication.

Production Patterns

In production, Jenkins is often run as a system service with custom JVM tuning, behind a reverse proxy (Nginx or Apache) for SSL termination, and uses external storage for JENKINS_HOME. CI/CD pipelines trigger Jenkins jobs remotely, and logs are aggregated centrally. WAR execution is mainly for quick tests or development.

Connections

Java Virtual Machine (JVM)

Jenkins WAR execution runs inside the JVM, relying on its runtime environment.

Understanding JVM behavior helps optimize Jenkins performance and troubleshoot memory or threading issues.

Web Servers and Servlet Containers

Jenkins WAR includes an embedded servlet container (Jetty) that serves web requests.

Knowing how servlet containers work clarifies how Jenkins handles web traffic and plugins.

Portable Software Packaging

Jenkins WAR is an example of portable software packaging allowing easy deployment.

This concept applies broadly to software distribution, like container images or single-file executables.

Common Pitfalls

#1 Trying to run Jenkins WAR without Java installed.

Wrong approach:

java -jar jenkins.war (on a system without Java)

Correct approach:

First install Java (e.g., OpenJDK), then run: java -jar jenkins.war

Root cause:

Assuming Jenkins WAR runs standalone without Java runtime.

#2 Running Jenkins WAR on a port already in use.

Wrong approach:

java -jar jenkins.war (when port 8080 is occupied)

Correct approach:

java -jar jenkins.war --httpPort=9090 (choose a free port)

Root cause:

Not checking port availability before starting Jenkins.

#3 Deleting the WAR file while Jenkins is running.

Wrong approach:

rm jenkins.war (while Jenkins process is active)

Correct approach:

Stop Jenkins first, then delete or replace the WAR file safely.

Root cause:

Not understanding that Jenkins runs from the WAR file and needs it during execution.

Key Takeaways

Jenkins WAR file execution lets you run Jenkins quickly anywhere with Java, without full installation.

The WAR file contains the entire Jenkins web app, but your data lives separately in the JENKINS_HOME directory.

You can customize Jenkins startup with options like port number, but running it directly is best for testing or small setups.

For production, experts use service managers, reverse proxies, and secure configurations beyond just running the WAR file.

Understanding the JVM and embedded web server inside the WAR helps optimize and troubleshoot Jenkins effectively.