Name	Name	Last commit message	Last commit date
parent directory ..
kokoro	kokoro
scripts	scripts
src	src
.gitignore	.gitignore
CHANGELOG.md	CHANGELOG.md
README.md	README.md
build.gradle	build.gradle
gradle.properties	gradle.properties

Jib - Containerize your Maven project

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.

☑️ Jib User Survey
What do you like best about Jib? What needs to be improved? Please tell us by taking a one-minute survey. Your responses will help us understand Jib usage and allow us to serve our customers (you!) better.

Upcoming Features
Quickstart
Extended Usage
Frequently Asked Questions (FAQ)
Community

Quickstart

You can containerize your application easily with one command:

mvn compile com.google.cloud.tools:jib-maven-plugin:2.0.0: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:2.0.0:dockerBuild

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

Setup

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>2.0.0</version>
        <configuration>
          <to>
            <image>myimage</image>
          </to>
        </configuration>
      </plugin>
      ...
    </plugins>
  </build>
  ...
</project>

Configuration

Configure the plugin by setting the image to push to:

Using Google Container Registry (GCR)...

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>

Using Amazon Elastic Container Registry (ECR)...

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>

Using Docker Hub Registry...

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>

Using Azure Container Registry (ACR)...

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 image

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.

Build to Docker daemon

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.

Build an image tarball

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

Bind to a lifecycle

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

Additional Build Artifacts

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 <outputFiles><digest> and <outputFiles><imageId> configuration properties. See Extended Usage for more details.

Extended Usage

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

Field	Type	Default	Description
`to`	`to`	Required	Configures the target image to build your application to.
`from`	`from`	See `from`	Configures the base image to build your application on top of.
`container`	`container`	See `container`	Configures the container that is run from your image.
`extraDirectories`	`extraDirectories`	See `extraDirectories`	Configures the directories used to add arbitrary files to the image.
`outputPaths`	`outputPaths`	See `outputPaths`	Configures the locations of additional build artifacts generated by Jib.
`dockerClient`	`dockerClient`	See `dockerClient`	Configures Docker for building to/from the Docker daemon.
`containerizingMode`	string	`exploded`	If set to `packaged`, puts the JAR artifact built at `${project.build.directory}/${project.build.finalName}.jar` (the default location where many JAR-buidiling plugins put a JAR registered as a main artifact, such as the Maven JAR Plugin) into the final image. If set to `exploded` (default), containerizes individual `.class` files and resources files.
`allowInsecureRegistries`	boolean	`false`	If set to true, Jib ignores HTTPS certificate errors and may fall back to HTTP as a last resort. Leaving this parameter set to `false` is strongly recommended, since HTTP communication is unencrypted and visible to others on the network, and insecure HTTPS is no better than plain HTTP. If accessing a registry with a self-signed certificate, adding the certificate to your Java runtime's trusted keys may be an alternative to enabling this option.
`skip`	boolean	`false`	If set to true, Jib execution is skipped (useful for multi-module projects). This can also be specified via the `-Djib.skip` command line option.

from is an object with the following properties:

Property	Type	Default	Description
`image`	string	`gcr.io/distroless/java`	The image reference for the base image. The source type can be specified using a special type prefix.
`auth`	`auth`	None	Specify credentials directly (alternative to `credHelper`).
`credHelper`	string	None	Specifies a credential helper that can authenticate pulling the base image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`).

to is an object with the following properties:

Property	Type	Default	Description
`image`	string	Required	The image reference for the target image. This can also be specified via the `-Dimage` command line option.
`auth`	`auth`	None	Specify credentials directly (alternative to `credHelper`).
`credHelper`	string	None	Specifies a credential helper that can authenticate pushing the target image. This parameter can either be configured as an absolute path to the credential helper executable or as a credential helper suffix (following `docker-credential-`).
`tags`	list	None	Additional tags to push to.

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

Property	Type
`username`	string
`password`	string

container is an object with the following properties:

Property	Type	Default	Description
`appRoot`	string	`/app`	The root directory on the container where the app's contents are placed. Particularly useful for WAR-packaging projects to work with different Servlet engine base images by designating where to put exploded WAR contents; see WAR usage as an example.
`args`	list	None	Additional program arguments appended to the command to start the container (similar to Docker's CMD instruction in relation with ENTRYPOINT). In the default case where you do not set a custom `entrypoint`, this parameter is effectively the arguments to the main method of your Java application.
`creationTime`	string	`EPOCH`	Sets the container creation time. (Note that this property does not affect the file modification times, which are configured using `<filesModificationTime>`.) The value can be `EPOCH` to set the timestamps to Epoch (default behavior), `USE_CURRENT_TIMESTAMP` to forgo reproducibility and use the real creation time, or an ISO 8601 date-time parsable with `DateTimeFormatter.ISO_DATE_TIME` such as `2019-07-15T10:15:30+09:00` or `2011-12-03T22:42:05Z`.
`entrypoint`	list	None	The command to start the container with (similar to Docker's ENTRYPOINT instruction). If set, then `jvmFlags` and `mainClass` are ignored. You may also set `<entrypoint>INHERIT</entrypoint>` to indicate that the `entrypoint` and `args` should be inherited from the base image.*
`environment`	map	None	Key-value pairs for setting environment variables on the container (similar to Docker's ENV instruction).
`extraClasspath`	list	None	Additional paths in the container to prepend to the computed Java classpath.
`filesModificationTime`	string	`EPOCH_PLUS_SECOND`	Sets the modification time (last modified time) of files in the image put by Jib. (Note that this does not set the image creation time, which can be set using `<creationTime>`.) The value should either be `EPOCH_PLUS_SECOND` to set the timestamps to Epoch + 1 second (default behavior), or an ISO 8601 date-time parsable with `DateTimeFormatter.ISO_DATE_TIME` such as `2019-07-15T10:15:30+09:00` or `2011-12-03T22:42:05Z`.
`format`	string	`Docker`	Use `OCI` to build an OCI container image.
`jvmFlags`	list	None	Additional flags to pass into the JVM when running your application.
`labels`	map	None	Key-value pairs for applying image metadata (similar to Docker's LABEL instruction).
`mainClass`	string	Inferred**	The main class to launch the application from.
`ports`	list	None	Ports that the container exposes at runtime (similar to Docker's EXPOSE instruction).
`user`	string	None	The user and group to run the container as. The value can be a username or UID along with an optional groupname or GID. The following are all valid: `user`, `uid`, `user:group`, `uid:gid`, `uid:group`, `user:gid`.
`volumes`	list	None	Specifies a list of mount points on the container.
`workingDirectory`	string	None	The working directory in the container.

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

Property	Type	Default	Description
`paths`	list	`[(project-dir)/src/main/jib]`	List of extra directories. Can be absolute or relative to the project root.
`permissions`	list	None	Maps file paths on container to Unix permissions. (Effective only for files added from extra directories.) If not configured, permissions default to "755" for directories and "644" for files.

outputPaths is an object with the following properties:

Property	Type	Default	Description
`tar`	string	`(project-dir)/target/jib-image.tar`	The path of the tarball generated by `jib:buildTar`. Relative paths are resolved relative to the project root.
`digest`	string	`(project-dir)/target/jib-image.digest`	The path of the image digest written out during the build. Relative paths are resolved relative to the project root.
`imageId`	string	`(project-dir)/target/jib-image.id`	The path of the image ID written out during the build. Relative paths are resolved relative to the project root.
`imageJson`	string	`(project-dir)/target/jib-image.json`	The path of the image metadata json file written out during the build. Relative paths are resolved relative to the project root.

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

Property	Type	Default	Description
`executable`	string	`docker`	Sets the path to the Docker executable that is called to load the image into the Docker daemon.
`environment`	map	None	Sets environment variables used by the Docker executable.

System 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:

Property	Type	Default	Description
`jib.httpTimeout`	int	`20000`	HTTP connection/read timeout for registry interactions, in milliseconds. Use a value of `0` for an infinite timeout.
`jib.useOnlyProjectCache`	boolean	`false`	If set to true, Jib does not share a cache between different Maven projects (i.e. `jib.baseImageCache` defaults to `[project dir]/target/jib-cache` instead of `[user cache home]/google-cloud-tools-java/jib`).
`jib.baseImageCache`	string	Platform-dependent***	Sets the directory to use for caching base image layers. This cache can (and should) be shared between multiple images.
`jib.applicationCache`	string	`[project dir]/target/jib-cache`	Sets the directory to use for caching application layers. This cache can be shared between multiple images.
`jib.console`	string	None	If set to `plain`, Jib will print plaintext log messages rather than display a progress bar during the build.

* 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)

Example

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 -Xms512m -Xdebug -Xmy:flag=jib-rules -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>-Xms512m</jvmFlag>
      <jvmFlag>-Xdebug</jvmFlag>
      <jvmFlag>-Xmy:flag=jib-rules</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>

Setting the Base Image

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:

Prefix	Example	Type
None	`gcr.io/distroless/java`	Pulls the base image from a registry.
`registry://`	`registry://gcr.io/distroless/java`	Pulls the base image from a registry.
`docker://`	`docker://busybox`	Retrieves the base image from the Docker daemon.
`tar://`	`tar:///path/to/file.tar`	Uses an image tarball stored at the specified path as the base image. Also accepts relative paths (e.g. `tar://target/jib-image.tar`).

Adding Arbitrary Files to the Image

* Note: this is an incubating feature and may change in the future.

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 image's root directory, 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).

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>
      <path>src/main/custom-extra-dir</path>
      <path>/home/user/jib-extras</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:

<configuration>
  <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>
    </permissions>
  </extraDirectories>
</configuration>

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

Authentication Methods

Pushing/pulling from private registries require authorization credentials. These can be retrieved using Docker credential helpers or defined in your Maven settings. If you do not define credentials explicitly, Jib will try to use credentials defined in your Docker config or infer common credential helpers.

Using Docker Credential Helpers

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>

Using Specific Credentials

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.

Property	Description
`-Djib.from.auth.username`	Username for base image registry.
`-Djib.from.auth.password`	Password for base image registry.
`-Djib.to.auth.username`	Username for target image registry.
`-Djib.to.auth.password`	Password for target image registry.

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.

Using Maven Settings

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.

WAR Projects

Jib also containerizes WAR projects. If the Maven project uses the war-packaging type, Jib will by default use the distroless 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 /jetty/webapps/ROOT, which is the expected WAR location for the distroless 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>

Frequently Asked Questions (FAQ)

See the Jib project FAQ.

Privacy

See the Privacy page.

Upcoming Features

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

Community

See the Jib project README.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

jib-maven-plugin

jib-maven-plugin

README.md

Jib - Containerize your Maven project

Table of Contents

Quickstart

Setup

Configuration

Using Google Container Registry (GCR)...

Using Amazon Elastic Container Registry (ECR)...

Using Docker Hub Registry...

Using Azure Container Registry (ACR)...

Build your image

Build to Docker daemon

Build an image tarball

Bind to a lifecycle

Additional Build Artifacts

Extended Usage

System Properties

Example

Setting the Base Image

Adding Arbitrary Files to the Image

Authentication Methods

Using Docker Credential Helpers

Using Specific Credentials

Using Maven Settings

WAR Projects

Frequently Asked Questions (FAQ)

Privacy

Upcoming Features

Community

Files

jib-maven-plugin

Directory actions

More options

Directory actions

More options

Latest commit

History

jib-maven-plugin

Folders and files

parent directory

README.md

Jib - Containerize your Maven project

Table of Contents

Quickstart

Setup

Configuration

Using Google Container Registry (GCR)...

Using Amazon Elastic Container Registry (ECR)...

Using Docker Hub Registry...

Using Azure Container Registry (ACR)...

Build your image

Build to Docker daemon

Build an image tarball

Bind to a lifecycle

Additional Build Artifacts

Extended Usage

System Properties

Example

Setting the Base Image

Adding Arbitrary Files to the Image

Authentication Methods

Using Docker Credential Helpers

Using Specific Credentials

Using Maven Settings

WAR Projects

Frequently Asked Questions (FAQ)

Privacy

Upcoming Features

Community