Jib is a Maven plugin for building Docker and OCI images for your Java applications.

For the Gradle plugin, see the jib-gradle-plugin project.

For information about the project, see the Jib project README.

• Upcoming Features
• Quickstart
  • Setup
  • Configuration
  • Build your image
    • Build to Docker Daemon
    • Build an image tarball
  • Bind to a lifecycle
  • Additional Build Artifacts
• Multi Module Projects
• Extended Usage
  • System Properties
  • Global Jib Configuration
  • Example
  • Adding Arbitrary Files to the Image
  • Authentication Methods
    • Using Docker configuration files
    • Using Docker Credential Helpers
    • Using Specific Credentials
    • Using Maven Settings
  • Custom Container Entrypoint
  • Jib Extensions
  • WAR Projects
  • Skaffold Integration
• Need Help?
• Community

You can containerize your application easily with one command:

mvn compile com.google.cloud.tools:jib-maven-plugin:3.4.1:build -Dimage=<MY IMAGE>

This builds and pushes a container image for your application to a container registry. If you encounter authentication issues, see Authentication Methods.

To build to a Docker daemon, use:

mvn compile com.google.cloud.tools:jib-maven-plugin:3.4.1:dockerBuild

If you would like to set up Jib as part of your Maven build, follow the guide below.

In your Maven Java project, add the plugin to your pom.xml:

<project>
  ...
  <build>
    <plugins>
      ...
      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.4.1</version>
        <configuration>
          <to>
            <image>myimage</image>
          </to>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Configure the plugin by setting the image to push to:

Make sure you have the docker-credential-gcr command line tool. Jib automatically uses docker-credential-gcr for obtaining credentials. See Authentication Methods for other ways of authenticating.

For example, to build the image gcr.io/my-gcp-project/my-app, the configuration would be:

<configuration>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
  </to>
</configuration>

Make sure you have the docker-credential-ecr-login command line tool. Jib automatically uses docker-credential-ecr-login for obtaining credentials. See Authentication Methods for other ways of authenticating.

For example, to build the image aws_account_id.dkr.ecr.region.amazonaws.com/my-app, the configuration would be:

<configuration>
  <to>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-app</image>
  </to>
</configuration>

Make sure you have a docker-credential-helper set up. For example, on macOS, the credential helper would be docker-credential-osxkeychain. See Authentication Methods for other ways of authenticating.

For example, to build the image my-docker-id/my-app, the configuration would be:

<configuration>
  <to>
    <image>docker.io/my-docker-id/my-app</image>
  </to>
</configuration>

Make sure you have a docker-credential-helper set up. For example, on macOS, the credential helper would be docker-credential-osxkeychain. See Authentication Methods for other ways of authenticating.

For example, to build the image my-company-docker-local.jfrog.io/my-app, the configuration would be:

<configuration>
  <to>
    <image>my-company-docker-local.jfrog.io/my-app</image>
  </to>
</configuration>

Make sure you have a ACR Docker Credential Helper installed and set up. For example, on Windows, the credential helper would be docker-credential-acr-windows. See Authentication Methods for other ways of authenticating.

For example, to build the image my_acr_name.azurecr.io/my-app, the configuration would be:

<configuration>
  <to>
    <image>my_acr_name.azurecr.io/my-app</image>
  </to>
</configuration>

Build your container image with:

mvn compile jib:build

Subsequent builds are much faster than the initial build.

Having trouble? Let us know by submitting an issue, contacting us on Gitter, or posting to the Jib users forum.

Jib can also build your image directly to a Docker daemon. This uses the docker command line tool and requires that you have docker available on your PATH.

mvn compile jib:dockerBuild

If you are using minikube's remote Docker daemon, make sure you set up the correct environment variables to point to the remote daemon:

eval $(minikube docker-env)
mvn compile jib:dockerBuild

Alternatively, you can set environment variables in the Jib configuration. See dockerClient for more configuration options.

You can build and save your image to disk as a tarball with:

mvn compile jib:buildTar

This builds and saves your image to target/jib-image.tar, which you can load into docker with:

docker load --input target/jib-image.tar

You can also bind jib:build to a Maven lifecycle, such as package, by adding the following execution to your jib-maven-plugin definition:

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  ...
  <executions>
    <execution>
      <phase>package</phase>
      <goals>
        <goal>build</goal>
      </goals>
    </execution>
  </executions>
</plugin>

Then, you can build your container image by running:

mvn package

As part of an image build, Jib also writes out the image digest and the image ID. By default, these are written out to target/jib-image.digest and target/jib-image.id respectively, but the locations can be configured using the <outputPaths><digest> and <outputPaths><imageId> configuration properties. See Extended Usage for more details.

Special handling of project dependencies is recommended when building complex multi module projects. See Multi Module Example for detailed information.

Extended configuration options provide additional options for customizing the image build.

from is an object with the following properties:

to is an object with the following properties:

auth is an object with the following properties (see Using Specific Credentials):

platform is an object with the following properties:

See How do I specify a platform in the manifest list (or OCI index) of a base image? for examples.

container is an object with the following properties:

extraDirectories is an object with the following properties (see Adding Arbitrary Files to the Image):

path is an object with the following properties (see Adding Arbitrary Files to the Image):

outputPaths is an object with the following properties:

dockerClient is an object used to configure Docker when building to/from the Docker daemon. It has the following properties:

Each of these parameters is configurable via commandline using system properties. Jib's system properties follow the same naming convention as the configuration parameters, with each level separated by dots (i.e. -Djib.parameterName[.nestedParameter.[...]]=value). Some examples are below:

mvn compile jib:build \
    -Djib.to.image=myregistry/myimage:latest \
    -Djib.to.auth.username=$USERNAME \
    -Djib.to.auth.password=$PASSWORD

mvn compile jib:dockerBuild \
    -Djib.dockerClient.executable=/path/to/docker \
    -Djib.container.environment=key1="value1",key2="value2" \
    -Djib.container.args=arg1,arg2,arg3

The following table contains additional system properties that are not available as build configuration parameters:

* If you configure args while entrypoint is set to 'INHERIT', the configured args value will take precedence over the CMD propagated from the base image.

** Uses the main class defined in the jar task or tries to find a valid main class.

*** The default base image cache is in the following locations on each platform:

• Linux: [cache root]/google-cloud-tools-java/jib/, where [cache root] is $XDG_CACHE_HOME ($HOME/.cache/ if not set)
• Mac: [cache root]/Google/Jib/, where [cache root] is $XDG_CACHE_HOME ($HOME/Library/Caches/ if not set)
• Windows: [cache root]\Google\Jib\Cache, where [cache root] is %XDG_CACHE_HOME% (%LOCALAPPDATA% if not set)

Some options can be set in the global Jib configuration file. The file is at the following locations on each platform:

• Linux: [config root]/google-cloud-tools-java/jib/config.json, where [config root] is $XDG_CONFIG_HOME ($HOME/.config/ if not set)
• Mac: [config root]/Google/Jib/config.json, where [config root] is $XDG_CONFIG_HOME ($HOME/Library/Preferences/ if not set)
• Windows: [config root]\Google\Jib\Config\config.json, where [config root] is %XDG_CONFIG_HOME% (%LOCALAPPDATA% if not set)

• disableUpdateCheck: when set to true, disables the periodic up-to-date version check.
• registryMirrors: a list of mirror settings for each base image registry. In the following example, if the base image configured in Jib is for a Docker Hub image, then mirror.gcr.io, localhost:5000, and the Docker Hub (registry-1.docker.io) are tried in order until Jib can successfully pull a base image.

{
  "disableUpdateCheck": false,
  "registryMirrors": [
    {
      "registry": "registry-1.docker.io",
      "mirrors": ["mirror.gcr.io", "localhost:5000"]
    },
    {
      "registry": "quay.io",
      "mirrors": ["private-mirror.test.com"]
    }
  ]
}

Note about mirror.gcr.io: it is not a Docker Hub mirror but a cache. It caches frequently-accessed public Docker Hub images, and it's often possible that your base image does not exist in mirror.gcr.io. In that case, Jib will have to fall back to use Docker Hub.

In this configuration, the image:

• Is built from a base of openjdk:alpine (pulled from Docker Hub)
• Is pushed to localhost:5000/my-image:built-with-jib, localhost:5000/my-image:tag2, and localhost:5000/my-image:latest
• Runs by calling java -Dmy.property=example.value -Xms512m -Xdebug -cp app/libs/*:app/resources:app/classes mypackage.MyApp some args
• Exposes port 1000 for tcp (default), and ports 2000, 2001, 2002, and 2003 for udp
• Has two labels (key1:value1 and key2:value2)
• Is built as OCI format

<configuration>
  <from>
    <image>openjdk:alpine</image>
  </from>
  <to>
    <image>localhost:5000/my-image:built-with-jib</image>
    <credHelper>osxkeychain</credHelper>
    <tags>
      <tag>tag2</tag>
      <tag>latest</tag>
    </tags>
  </to>
  <container>
    <jvmFlags>
      <jvmFlag>-Dmy.property=example.value</jvmFlag>
      <jvmFlag>-Xms512m</jvmFlag>
      <jvmFlag>-Xdebug</jvmFlag>
    </jvmFlags>
    <mainClass>mypackage.MyApp</mainClass>
    <args>
      <arg>some</arg>
      <arg>args</arg>
    </args>
    <ports>
      <port>1000</port>
      <port>2000-2003/udp</port>
    </ports>
    <labels>
      <key1>value1</key1>
      <key2>value2</key2>
    </labels>
    <format>OCI</format>
  </container>
</configuration>

There are three different types of base images that Jib accepts: an image from a container registry, an image stored in the Docker daemon, or an image tarball on the local filesystem. You can specify which you would like to use by prepending the <from><image> configuration with a special prefix, listed below:

You can add arbitrary, non-classpath files to the image by placing them in a src/main/jib directory. This will copy all files within the jib folder to the target directory (/ by default) in the image, maintaining the same structure (e.g. if you have a text file at src/main/jib/dir/hello.txt, then your image will contain /dir/hello.txt after being built with Jib).

Note that Jib does not follow symbolic links in the container image. If a symbolic link is present, it will be removed prior to placing the files and directories.

You can configure different directories by using the <extraDirectories> parameter in your pom.xml:

<configuration>
  <!-- Copies files from 'src/main/custom-extra-dir' and '/home/user/jib-extras' instead of 'src/main/jib' -->
  <extraDirectories>
    <paths>
      <!-- Copies from 'src/main/custom-extra-dir' into '/' on the container. -->
      <path>src/main/custom-extra-dir</path>
      <!-- Copies from '/home/user/jib-extras' into '/extras' on the container -->
      <path>
        <from>/home/user/jib-extras</from>
        <into>/extras</into>
      </path>
    </paths>
  </extraDirectories>
</configuration>

Alternatively, the <extraDirectories> parameter can be used as an object to set custom extra directories, as well as the extra files' permissions on the container:

  <extraDirectories>
    <paths>src/main/custom-extra-dir</paths> <!-- Copies files from 'src/main/custom-extra-dir' -->
    <permissions>
      <permission>
        <file>/path/on/container/to/fileA</file>
        <mode>755</mode> <!-- Read/write/execute for owner, read/execute for group/other -->
      </permission>
      <permission>
        <file>/path/to/another/file</file>
        <mode>644</mode> <!-- Read/write for owner, read-only for group/other -->
      </permission>
      <permission>
        <file>/glob/pattern/**/*.sh</file>
        <mode>755</mode>
      </permission>
    </permissions>
  </extraDirectories>

You may also specify the target of the copy and include or exclude files:

  <extraDirectories>
    <paths>
      <path>
        // copies the contents of 'src/main/extra-dir' into '/' on the container
        <from>src/main/extra-dir</from>
      </path>
      <path>
        // copies the contents of 'src/main/another/dir' into '/extras' on the container
        <from>src/main/another/dir</from>
        <into>/extras</into>
      </path>
      <path>
        // copies a single-file.xml
        <from>src/main/resources/xml-files</from>
        <into>/dest-in-container</into>
        <includes>single-file.xml</includes>
      </path>
      <path>
        // copies only .txt files except for 'hidden.txt' at the source root
        <from>build/some-output</from>
        <into>/txt-files</into>
        <includes>*.txt,**/*.txt</includes>
        <excludes>
          <exclude>hidden.txt</exclude>
        </excludes>
      </path>
    </paths>
  </extraDirectories>

Pushing/pulling from private registries require authorization credentials.

• Jib looks from credentials from $XDG_RUNTIME_DIR/containers/auth.json, $XDG_CONFIG_HOME/containers/auth.json, $HOME/.config/containers/auth.json, $DOCKER_CONFIG/config.json, and $HOME/.docker/config.json.

See this issue and man containers-auth.json for more information about the files.

Docker credential helpers are CLI tools that handle authentication with various registries.

Some common credential helpers include:

• Google Container Registry: docker-credential-gcr
• AWS Elastic Container Registry: docker-credential-ecr-login
• Docker Hub Registry: docker-credential-*
• Azure Container Registry: docker-credential-acr-*

Configure credential helpers to use by specifying them as a credHelper for their respective image.

Example configuration:

<configuration>
  ...
  <from>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image</image>
    <credHelper>ecr-login</credHelper>
  </from>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
    <credHelper>gcr</credHelper>
  </to>
  ...
</configuration>

You can specify credentials directly in the <auth> parameter for the from and/or to images. In the example below, to credentials are retrieved from the REGISTRY_USERNAME and REGISTRY_PASSWORD environment variables.

<configuration>
  ...
  <from>
    <image>aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image</image>
    <auth>
      <username>my_username</username>
      <password>my_password</password>
    </auth>
  </from>
  <to>
    <image>gcr.io/my-gcp-project/my-app</image>
    <auth>
      <username>${env.REGISTRY_USERNAME}</username>
      <password>${env.REGISTRY_PASSWORD}</password>
    </auth>
  </to>
  ...
</configuration>

Alternatively, you can specify credentials via commandline using the following system properties.

e.g. mvn compile jib:build -Djib.to.auth.username=user -Djib.to.auth.password=pass

Note: This method of authentication should be used only as a last resort, as it is insecure to make your password visible in plain text. Note that often cloud registries (for example, Google GCR, Amazon ECR, and Azure ACR) do not accept "user credentials" (such as Gmail account name and password) but require different forms of credentials. For example, you may use oauth2accesstoken or _json_key as the username for GCR, and AWS for ECR. For ACR, you may use a service principle.

Registry credentials can be added to your Maven settings. These credentials will be used if credentials could not be found in any specified Docker credential helpers.

If you're considering putting credentials in Maven, we highly recommend using maven password encryption.

Example settings.xml:

<settings>
  ...
  <servers>
    ...
    <server>
      <id>MY_REGISTRY</id>
      <username>MY_USERNAME</username>
      <password>{MY_SECRET}</password>
    </server>
  </servers>
</settings>

• The id field should be the registry server these credentials are for.
• We do not recommend putting your raw password in settings.xml.

If you don't set <container><entrypoint>, the default container entrypoint to launch your app will be basically java -cp <runtime classpath> <app main class>. (The final java command can be further configured by setting <container>{<jvmFlags>|<args>|<extraClasspath>|<mainClass>|<expandClasspathDependencies>}.)

Sometimes, you'll want to set a custom entrypoint to use a shell to wrap the java command. For example, to let sh or bash expand environment variables, or to have more sophisticated logic to construct a launch command. (Note, however, that running a command with a shell forks a new child process unless you run it with exec like sh -c "exec java ...". Whether to run the JVM process as PID 1 or a child process of a PID-1 shell is a decision you should make carefully.) In this scenario, you will want to have a way inside a shell script to reliably know the default runtime classpath and the main class that Jib would use by default. To help this, Jib >= 3.1 creates two JVM argument files under /app (the default app root) inside the built image.

• /app/jib-classpath-file: runtime classpath that Jib would use for default app launch
• /app/jib-main-class-file: main class

Therefore, for example, the following commands will be able to launch your app:

• (Java 9+) java -cp @/app/jib-classpath-file @/app/jib-main-class-file
• (with shell) java -cp $( cat /app/jib-classpath-file ) $( cat /app/jib-main-class-file )

The Jib build plugins have an extension framework that enables anyone to easily extend Jib's behavior to their needs. We maintain select first-party plugins for popular use cases like fine-grained layer control, builds a GraalVM native image, and Quarkus support, but anyone can write and publish an extension. Check out the jib-extensions repository for more information.

Jib also containerizes WAR projects. If the Maven project uses the war-packaging type, Jib will by default use jetty as a base image to deploy the project WAR. No extra configuration is necessary other than having the packaging type to war.

Note that Jib will work slightly differently for WAR projects from JAR projects:

• <container><mainClass> and <container><jvmFlags> are ignored.
• The WAR will be exploded into /var/lib/jetty/webapps/ROOT, which is the expected WAR location for the Jetty base image.

To use a different Servlet engine base image, you can customize <container><appRoot>, <container><entrypoint>, and <container><args>. If you do not set entrypoint or args, Jib will inherit the ENTRYPOINT and CMD of the base image, so in many cases, you may not need to configure them. However, you will most likely have to set <container><appRoot> to a proper location depending on the base image. Here is an example of using a Tomcat image:

<configuration>
  <from>
    <image>tomcat:8.5-jre8-alpine</image>
  </from>
  <container>
    <!--
      For demonstration only: this directory in the base image contains a Tomcat default
      app (welcome page), so you may first want to delete this directory in the base image.
    -->
    <appRoot>/usr/local/tomcat/webapps/ROOT</appRoot>
  </container>
</configuration>

When specifying a jetty image yourself with <from><image>, you may run into an issue (#3204) and need to override the entrypoint.

<configuration>
  <from>
    <image>jetty:11.0.2-jre11</image>
  </from>
  <container>
    <entrypoint>java,-jar,/usr/local/jetty/start.jar</entrypoint>
  </container>
</configuration>

Jib is an included builder in Skaffold. Jib passes build information to skaffold through special internal goals so that skaffold understands when it should rebuild or synchronize files. For complex builds, the defaults may not be sufficient, so the jib plugin provides a skaffold configuration object which exposes:

watch is an object with the following properties:

sync is an object with the following properties:

A lot of questions are already answered!

• Frequently Asked Questions (FAQ)
• Stack Overflow
• GitHub issues

For usage questions, please ask them on Stack Overflow.

See the Privacy page.

See Milestones for planned features. Get involved with the community for the latest updates.

See the Jib project README.

This is not an officially supported Google product.