Update FAQ for Jib CLI

docs/faq.md

@@ -7,6 +7,7 @@ If a question you have is not answered below, please [submit an issue](/../../is
 | What do you like best about Jib? What needs to be improved? Please tell us by taking a [one-minute survey](https://forms.gle/YRFeamGj51xmgnx28). Your responses will help us understand Jib usage and allow us to serve our customers (you!) better. |
 
 [But, I'm not a Java developer.](#but-im-not-a-java-developer)\
+[My build process doesn't let me integrate with the Jib Maven or Gradle plugin](#my-build-process-doesnt-let-me-integrate-with-the-jib-maven-or-gradle-plugin)\
 [How do I run the image I built?](#how-do-i-run-the-image-i-built)\
 [Where is bash?](#where-is-bash)\
 [What image format does Jib use?](#what-image-format-does-jib-use)\
@@ -47,6 +48,10 @@ If a question you have is not answered below, please [submit an issue](/../../is
 [I am seeing `Method Not Found` or `Class Not Found` errors when building.](#i-am-seeing-method-not-found-or-class-not-found-errors-when-building)\
 [Why won't my container start?](#why-wont-my-container-start)
 
+**Jib CLI**\
+[How does the `jar` command support Standard JARs?](#how-does-the-jar-command-support-standard-jars)\
+[How does the `jar` command support Spring Boot JARs?](#how-does-the-jar-command-support-spring-boot-jars)
+
 ---
 
 ### But, I'm not a Java developer.
@@ -55,6 +60,16 @@ Check out [Jib CLI](https://github.com/GoogleContainerTools/jib/tree/master/jib-
 
 Also see [rules_docker](https://github.com/bazelbuild/rules_docker) for a similar existing container image build tool for the [Bazel build system](https://github.com/bazelbuild/bazel). The tool can build images for languages such as Python, NodeJS, Java, Scala, Groovy, C, Go, Rust, and D.
 
+### My build process doesn't let me integrate with the Jib Maven or Gradle plugin
+
+The [Jib CLI](https://github.com/GoogleContainerTools/jib/tree/master/jib-cli) can be useful for users with complex build workflows that make it hard to integrate the Jib Maven or Gradle plugin. It is a standalone application that is powered by [Jib Core](https://github.com/GoogleContainerTools/jib/tree/master/jib-core) and offers two commands:
+
+* [Build](https://github.com/GoogleContainerTools/jib/tree/master/jib-cli#build-command): Builds images from the filesystem content.
+
+* [Jar](https://github.com/GoogleContainerTools/jib/tree/master/jib-cli#jar-command): Examines your JAR and builds an image with optimized layers or containerizes the JAR as-is.
+
+Check out the [Jib CLI section](#jib-cli) of the FAQ for more information.
+
 ### How do I run the image I built?
 
 If you built your image directly to the Docker daemon using `jib:dockerBuild` (Maven) or `jibDockerBuild` (Gradle), you simply need to use `docker run <image name>`.
@@ -168,11 +183,12 @@ Jib packages your Java application into the following paths on the image:
 Jib makes use of [layering](https://containers.gitbook.io/build-containers-the-hard-way/#layers) to allow for fast rebuilds - it will only rebuild the layers containing files that changed since the previous build and will reuse cached layers containing files that didn't change. Jib organizes files in a way that groups frequently changing files separately from large, rarely changing files. For example, `SNAPSHOT` dependencies are placed in a separate layer from other dependencies, so that a frequently changing `SNAPSHOT` will not force the entire dependency layer to rebuild itself.
 
 Jib applications are split into the following layers:
-* Classes
-* Resources
-* Project dependencies
-* Snapshot dependencies
+
 * All other dependencies
+* Snapshot dependencies
+* Project dependencies
+* Resources
+* Classes
 * Each extra directory (`jib.extraDirectories` in Gradle, `<extraDirectories>` in Maven) builds to its own layer
 
 ### Can I learn more about container images?
@@ -756,3 +772,59 @@ On examining the container structure with [Dive](https://github.com/wagoodman/di
 The user had used Jib's ability to install extra files into the image ([Maven](https://github.com/GoogleContainerTools/jib/tree/master/jib-maven-plugin#adding-arbitrary-files-to-the-image), [Gradle](https://github.com/GoogleContainerTools/jib/tree/master/jib-gradle-plugin#adding-arbitrary-files-to-the-image)) to install a library file by placing it in `src/main/jib/lib/libfoo.so`. This would normally cause the `libfoo.so` to be installed in the image as `/lib/libfoo.so`. But `/lib` and `/lib64` in the user's base image were symbolic links. Jib does not follow such symbolic links when creating the image. And at container initialization time, Docker treats these symlinks as a file, and thus the symbolic link was replaced with `/lib` as a new directory. As a result, none of the system shared libraries were resolved and dynamically-linked programs failed.
 
 Solution: The user installed the file in a different location.
+
+## Jib CLI 
+
+### How does the `jar` command support Standard JARs?
+The Jib CLI supports both [thin JARs](https://docs.oracle.com/javase/tutorial/deployment/jar/downman.html) (where dependencies are specified in the JAR's manifest) and fat JARs.
+
+However, the current limitation of using a fat JAR is that the embedded dependencies will not be placed into the designated dependencies layers.
+They will instead be placed into the classes or resources layer. We hope to have better support for fat JARs in the future.
+
+A standard JAR can be containerized by the `jar` command in two modes, exploded or packaged. 
+
+#### Exploded Mode (Recommended)
+Achieved by calling `jib jar --target ${TARGET_REGISTRY} ${JAR_NAME}.jar`
+
+The default mode for containerizing a JAR. It will open up the JAR and optimally place files into the following layers:  
+
+* Other Dependencies Layer
+* Snapshot-Dependencies Layer
+* Resources Layer
+* Classes Layer
+
+**Entrypoint** : `java -cp /app/dependencies/:/app/explodedJar/ ${MAIN_CLASS}`
+
+#### Packaged Mode
+Achieved by calling `jib jar --target ${TARGET_REGISTRY} ${JAR_NAME}.jar --mode packaged`.
+
+It will result in the following layers on the container:
+
+* Dependencies Layer
+* Jar Layer
+
+**Entrypoint** : `java -jar ${JAR_NAME}.jar`
+
+### How does the `jar` command support Spring Boot JARs?
+The `jar` command currently supports containerization of Spring Boot fat JARs.
+A Spring-Boot fat JAR can be containerized in two modes, exploded or packaged. 
+
+#### Exploded Mode (Recommended)
+Achieved by calling `jib jar --target ${TARGET_REGISTRY} ${JAR_NAME}.jar`
+
+The default mode for containerizing a JAR. It will respect [`layers.idx`](https://spring.io/blog/2020/08/14/creating-efficient-docker-images-with-spring-boot-2-3) (if present) or create layers in the following format:
+
+* Other Dependencies Layer
+* Spring-Boot-Loader Layer
+* Snapshot-Dependencies Layer
+* Resources Layer
+* Classes Layer
+
+**Entrypoint** : `java -cp /app org.springframework.boot.loader.JarLauncher`
+
+#### Packaged Mode
+Achieved by calling `jib jar --target ${TARGET_REGISTRY} ${JAR_NAME}.jar --mode packaged`
+
+It will containerize the JAR as is. However, **note** that we highly recommend against using packaged mode for containerizing Spring Boot fat JARs. 
+
+**Entrypoint**: `java -jar ${JAR_NAME}.jar`