From Code to Cloud: Understanding the Spring Boot Fat Jar

“A standard JAR is like a monkey with a recipe. A Spring Boot ‘fat JAR’ is a monkey that comes with its own backpack containing the recipe, all the ingredients, and a portable stove. It’s completely self-sufficient! 🐒🎒”

You’ve written the code, run the tests, and your Spring Boot application works perfectly on your machine. Now comes the big question: how do you package it up and run it somewhere else, like on a server in the cloud? In the old days, this involved building a WAR file, deploying it to a hefty application server like Tomcat or JBoss, and managing a jungle of external dependencies.

Spring Boot revolutionizes this with the concept of the executable “fat JAR”. It’s a single, self-contained file that has everything your application needs to run. No external server required, no dependency headaches. In this tutorial, we’ll unpack this magic backpack, see what’s inside, and understand how it makes deploying Java applications monkey-proof.

Prerequisites

• A simple Spring Boot application (a “Hello, World” REST controller is perfect).
• Java (JDK) 17 or higher installed.
• Maven or Gradle installed and configured.

1️⃣ What’s in the Backpack? Deconstructing the Fat JAR

First, let’s build our application and create the JAR file. Navigate to the root of your Spring Boot project in your terminal and run the standard Maven package command:

mvn clean package

After the build succeeds, you’ll find your JAR file in the target/ directory (e.g., my-app-0.0.1-SNAPSHOT.jar). This isn’t just any JAR file; it’s a carefully structured archive. We can peek inside using a command like unzip -l or by opening it with any archive manager.

unzip -l target/my-app-0.0.1-SNAPSHOT.jar

You’ll see a structure like this:

Archive:  my-app-0.0.1-SNAPSHOT.jar
  Length      Date    Time    Name
---------  ---------- -----   ----
...
        0  2023-10-27 10:00   BOOT-INF/
        0  2023-10-27 10:00   BOOT-INF/classes/
...
     1234  2023-10-27 10:00   BOOT-INF/classes/com/example/myapp/MyApplication.class
...
        0  2023-10-27 10:00   BOOT-INF/lib/
...
   987123  2023-10-27 10:00   BOOT-INF/lib/spring-boot-starter-web-3.1.5.jar
   456789  2023-10-27 10:00   BOOT-INF/lib/spring-core-6.0.13.jar
   345678  2023-10-27 10:00   BOOT-INF/lib/tomcat-embed-core-10.1.15.jar
...
        0  2023-10-27 10:00   META-INF/
     123   2023-10-27 10:00   META-INF/MANIFEST.MF
...

Let’s break down the key ingredients in this backpack:

• BOOT-INF/classes/: This is your monkey’s recipe. It contains all of your application’s compiled code (the .class files).
• BOOT-INF/lib/: These are the ingredients. This directory holds all the dependency JARs your project needs, like spring-web, jackson-databind, and even an embedded web server like tomcat-embed-core.
• META-INF/MANIFEST.MF: This is the instruction manual. It tells the Java runtime how to start the application.

2️⃣ The Magic Backpack-Maker: The spring-boot-maven-plugin

So, who packs this magical backpack for us? The credit goes to the spring-boot-maven-plugin. When you create a project from start.spring.io, this plugin is automatically included in your pom.xml:

<build>
    <plugins>
        <plugin>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-maven-plugin</artifactId>
        </plugin>
    </plugins>
</build>

This plugin has a special goal called repackage. During the package phase of the build, Maven first creates a standard, “thin” JAR with just your code. Then, the repackage goal kicks in. It takes that thin JAR, pulls in all the dependencies, adds the special Spring Boot loader classes, and repackages everything into the final, executable fat JAR. (For Gradle users, the bootJar task does the same thing).

3️⃣ Lighting the Stove: How java -jar Works

The true magic is how Spring Boot enables a standard java -jar command to run this complex archive. A normal Java classloader can’t load classes from JARs that are nested inside another JAR. Spring Boot solves this with a clever trick.

If you inspect the META-INF/MANIFEST.MF file inside the JAR, you’ll see a special entry:

Main-Class: org.springframework.boot.loader.JarLauncher
Start-Class: com.example.myapp.MyApplication

When you run java -jar my-app.jar, the JVM doesn’t run your main class directly. Instead, it runs Spring Boot’s JarLauncher. This special launcher class acts as the entry point. It understands the fat JAR’s structure and sets up a custom classloader that knows how to load classes and dependencies from the nested JARs inside BOOT-INF/lib/ and BOOT-INF/classes/. Once the environment is ready, it finally calls the main method of your application’s Start-Class.

4️⃣ Recipe vs. Meal Kit: Thin vs. Fat JARs

To really appreciate the fat JAR, let’s compare it to a traditional “thin” JAR.

💡 Monkey-Proof Tips

• Deployment Dream: The fat JAR is the reason deploying Spring Boot apps is so simple. You just need a Java Runtime Environment on the target machine. You copy one file, run one command, and you’re done. This completely eliminates the “it works on my machine” problem.
• Container-Friendly: This self-contained model is perfect for containerization with tools like Docker. Your Dockerfile can be as simple as copying the fat JAR into an image and setting the java -jar command as the entry point.

🚀 Challenge

Time to pack your own backpack and light the stove!

1. Take any Spring Boot application you’ve built.
2. Run mvn clean package (or gradle bootJar) from your terminal.
3. Navigate to the target (or build/libs) directory and find the generated JAR file.
4. Run your application directly from the command line: java -jar your-app-name.jar. You should see the familiar Spring Boot startup banner!
5. Bonus: Stop the application. Now, use the unzip -l your-app-name.jar | grep tomcat command. Can you see the embedded web server packed right inside your JAR?

👏 Congratulations! You’ve successfully demystified one of Spring Boot’s most powerful and convenient features. By understanding the fat JAR, you’ve taken a huge step toward being able to package, ship, and run your applications anywhere with confidence.