Packaging and Running: Fat Jars and Graceful Shutdown

Deploying a Java web application used to mean four chores: install a JDK, install Tomcat, drop the war into webapps, then pray the server's versions match your laptop's. Spring Boot compresses all four into one line: java -jar app.jar. This article covers the three things behind that sentence — what is actually inside the jar, how it boots itself, and how to make it stop with dignity.

Six words, one line each (used throughout):

• fat jar (executable jar): the jar with every dependency packed inside, also called an uber-jar; Boot's repackage goal produces it
• MANIFEST.MF: the instruction sheet inside the jar; its Main-Class tells the JVM whose main to run
• BOOT-INF/: the directory inside a fat jar holding your classes and dependencies — invisible to a standard JVM, reachable only through Boot's own loader
• ClassLoader: the layer that "finds bytecode by name and turns it into a Class object"; Java lets you write your own
• SIGTERM / SIGKILL: two Unix stop signals — the first says "pack your bags and leave", the second says "the power just went out"
• profile / external config: the mechanism letting one jar read different files per environment, so ops never repackage to change a URL

After this article you should be able to answer three questions:

• Why must java -cp app.jar com.example.BeeApplication fail while java -jar app.jar works?
• Why should -Xmx become -XX:MaxRAMPercentage inside a container?
• How do you restart a production service without users noticing? (Hint: two config lines plus one signal.)

The first time you use Spring Boot you wonder: why does java -jar app.jar run an entire web service? With classic Spring MVC you built a war, dropped it into an external Tomcat's webapps, and made sure the server had the right Tomcat version. Spring Boot stuffs all of that into a single jar.

war is not useless — it serves the historical case of "the company maintains a fleet of Tomcats and apps must be deployed into them". For new projects the fat jar wins decisively: the application and its runtime become one indivisible deliverable, copy-and-run, a natural fit for one-process-per-container.

The most direct way to understand it is to unpack it. Run unzip -l (or jar tf):

Three key areas:

• BOOT-INF/classes/: your own bytecode and config (application.yml, static/)
• BOOT-INF/lib/: every third-party dependency, stored as nested jars — not unpacked classes
• org/springframework/boot/loader/: Spring Boot's own loader and launcher code

Now the manifest:

Seeing Main-Class: JarLauncher explains it: java -jar starts Spring Boot's JarLauncher, not your BeeApplication. The full chain is:

1. You run java -jar app.jar
2. The JVM reads the MANIFEST, sees Main-Class: JarLauncher, and reflectively calls its main
3. JarLauncher reads Start-Class from the same MANIFEST and learns the real entry point is BeeApplication
4. It creates a special LaunchedURLClassLoader and **wires BOOT-INF/lib/.jar and BOOT-INF/classes/ onto its search path*
5. It loads and reflectively invokes BeeApplication.main with that loader

Extend that chain one box upstream and you have the artifact's whole life — most people only stare at java -jar, unaware that the build step repackage is what makes the jar self-running at all:

The core problem it solves is "jar in jar": Java was never designed to hold jars inside a jar. A standard JVM reads flat archives and cannot open nested dependencies. Spring Boot's answer is a custom URL protocol plus a JarFile extension: it maps each nested jar entry to a special URL that LaunchedURLClassLoader opens one by one, so the JVM's class loading finally "sees" those nested dependencies.

"Two loaders, two visibilities" is easier to follow as a hand-off than as a diagram. This animation runs it in seven frames; note frame 2, when the standard loader still has no idea your classes exist:

Now spread the five-step chain out as a single-step run. The left column is what this JVM does in order; the right panel refreshes "what Main-Class says" and "who can see whom" as you go. Watch beat 3 (the road gets built) and beat 5 (the wheel gets handed over):

The same fact seen from the other side is a layering question. Click from ① to ⑤; box ② is the one most people get wrong in an interview:

Packaging is not hard; the tricky part is what to skip and which environment to activate.

Every one of those flags assumes a precondition: the pom contains spring-boot-maven-plugin. That single line is the switch for repackage, and the watershed between "a jar that runs itself" and "a few hundred KB of ordinary archive". Tick it through — and look at the scope on test, because that is exactly what -DskipTests is arguing about:

The flags above are only seasoning; the lifecycle is the conveyor belt itself. Before touching the pom, watch what a single mvn package actually runs, and in what order — press the four parameters in sequence:

Now revisit the table above with those four pictures in mind: -Pprod swaps the profile, -DskipTests flips a surefire switch, but the package phase itself always drags along every goal bound to it.

Multi-environment packaging, declared in pom.xml:

java -jar takes more than a path; keep JVM flags and application arguments separate:

This is the most important part of the article. Many production "data inconsistency" incidents come not from business code but from stopping the process the wrong way.

Think about what kill -9 does: the JVM receives SIGKILL and no callback runs at all. A "debit plus reward points" transaction that has debited but not yet credited is torn in half; a request read into memory but not yet returned is cut off and the client sees a connection reset; pooled connections are ripped away while the database still holds an "uncommitted transaction".

Spring Boot offers graceful shutdown in two lines:

Once enabled, a normal kill <pid> (no -9) follows this complete path:

1. Receive SIGTERM: kill, systemd stop, docker stop and K8s pod deletion all send this, not -9
2. Stop accepting new requests: the web connector closes; the load balancer detects unhealthy and drains traffic
3. Wait for in-flight requests: bounded by timeout-per-shutdown-phase, or until they drain
4. Close the context and fire destroy callbacks: @PreDestroy, DisposableBean#destroy, @Bean(destroyMethod) in order
5. Shut down pools and resources: thread pools, data sources, messaging clients wrap up
6. JVM exits

Plain nohup java -jar ... & has two problems: no PID to stop cleanly, and no idea whether the service actually started. A practical script manages the PID and waits for a health check:

On production hosts the cleaner approach is systemd, which supports graceful shutdown natively (it sends SIGTERM by default) and restarts on crash:

On K8s or multi-instance environments, /actuator/health is how the orchestrator decides whether an instance may take traffic. It distinguishes two probes: readiness (join load balancing) and liveness (restart the instance). Graceful shutdown plus a readiness probe is what makes "drain traffic, then stop the process" invisible to users.

Enabling probes exposes dedicated /actuator/health/readiness and /actuator/health/liveness endpoints — the next article, "Docker Deployment", wires them into an orchestration file.

After packaging, application.yml, templates and certificates live inside the jar, not on a filesystem path:

To change a database URL, many people unzip the jar, edit the config, and zip it back — easily corrupting the zip structure. The right approach is external config override: Spring Boot prefers application.yml next to the jar or in a config/ subdirectory.

That chain — "edit a file" to "never repack again" — deserves its own walkthrough, because shipping a release every time a database password changes is a lesson nearly every team has paid for:

If a line like Started BeeApplication in 8.3 seconds keeps growing, something heavy happens at startup: scanning many beans, initializing pools, warming caches, fetching remote config. Use --debug or add spring-boot-starter-actuator to inspect startup metrics and find the slow segment instead of optimizing blindly.

The "it runs in the IDE but not under java -jar" story has a nastier variant: the application starts fine, and then some bean trips over a resource that never becomes a real file on disk. Here is that live scene — do not read the notes yet, click the frame you believe is the culprit:

From the moment Spring Boot's main is called to the moment it can serve, a great many beans are created and wired. This demo runs the container's assembly — understanding bean creation order means understanding where startup time goes.

• Toggle the condition switches (@ConditionalOn*) and watch the same code assemble different beans
• More beans and deeper dependency chains mean slower startup — the root cause of "a large app takes tens of seconds to boot"
• To speed it up: trim unnecessary auto-configurations, use lazy-initialization, or move heavy work to after startup

The second lab opens the fat jar itself, so the layout stops being a diagram you memorized and becomes something you can look inside. Start with layout, then loader.

The third lab moves one level up: what the JVM does while Docker builds an image, and why the image is far larger than the jar it contains.

The fourth lab walks the shutdown path — the one that decides whether a deploy corrupts data or not.

Enough buttons — type the same things yourself. This console talks to the same in-browser kernel, and every reply is computed there: start with whoami to see which class loader is running, probe the app with curl /actuator/health, then walk the labs one by one: