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

• Fast - Deploy your changes fast. Jib separates your application into multiple layers, splitting dependencies from classes. Now you don’t have to wait for Docker to rebuild your entire Java application - just deploy the layers that changed.

• Reproducible - Rebuilding your container image with the same contents always generates the same image. Never trigger an unnecessary update again.

• Native - Reduce your CLI dependencies. Build your Docker image from within Maven and push to any registry of your choice. No more writing Dockerfiles and calling docker build/push.

These features are not currently supported but will be added in later releases.

• Support for WAR format

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

<plugin>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-maven-plugin</artifactId>
  <version>0.1.6</version>
  <configuration>
    <registry>myregistry</registry>
    <repository>myapp</repository>
  </configuration>
</plugin>

Configure the plugin by changing registry and repository to be the registry and repository to push the built image 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>
  <registry>gcr.io</registry>
  <repository>my-gcp-project/my-app</repository>
</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>
  <registry>aws_account_id.dkr.ecr.region.amazonaws.com</registry>
  <repository>my-app</repository>
</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>
  <registry>registry.hub.docker.com</registry>
  <repository>my-docker-id/my-app</repository>
  <credHelpers><credHelper>osxkeychain</credHelper></credHelpers>
</configuration>

Build your container image with:

mvn compile jib:build

Subsequent builds are much faster than the initial build.

If you want to clear Jib's build cache and force it to re-pull the base image and re-build the application layers, run:

mvn clean compile jib:build

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

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.com.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

Jib can also export to a Docker context so that you can build with Docker, if needed:

mvn compile jib:dockercontext

The Docker context will be created at target/jib-dockercontext by default. You can change this directory with the targetDir configuration option or the jib.dockerDir parameter:

mvn compile jib:dockercontext -Djib.dockerDir=my/docker/context/

You can then build your image with Docker:

docker build -t myregistry/myapp my/docker/context/

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

In this configuration, the image is:

• Built from a base of openjdk:alpine (pulled from Docker Hub)
• Pushed to localhost:5000/my-image:built-with-jib
• Runs by calling java -Xms512m -Xdebug -Xmy:flag=jib-rules -cp app/libs/*:app/resources:app/classes mypackage.MyApp
• Reproducible
• Built as OCI format

<configuration>
  <from>openjdk:alpine</from>
  <registry>localhost:5000</registry>
  <repository>my-image</repository>
  <tag>built-with-jib</tag>
  <credHelpers>
    <credHelper>osxkeychain</credHelper>
  </credHelpers>
  <jvmFlags>
    <jvmFlag>-Xms512m</jvmFlag>
    <jvmFlag>-Xdebug</jvmFlag>
    <jvmFlag>-Xmy:flag=jib-rules</jvmFlag>
  </jvmFlags>
  <mainClass>mypackage.MyApp</mainClass>
  <enableReproducibleBuilds>true</enableReproducibleBuilds>
  <imageFormat>OCI</imageFormat>
</configuration>

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.

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

Configure credential helpers to use by specifying them in the credHelpers configuration.

Example configuration:

<configuration>
  ...
  <credHelpers>
    <credHelper>osxkeychain</credHelper>
  </credHelpers>
  ...
</configuration>

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.

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.

Whereas traditionally a Java application is built as a single image layer with the application JAR, Jib's build strategy separates the Java application into multiple layers for more granular incremental builds. When you change your code, only your changes are rebuilt, not your entire application. These layers, by default, are layered on top of a distroless base image.

See also rules_docker for a similar existing container image build tool for the Bazel build system.

These limitations will be fixed in later releases.

• Cannot build directly to a Docker daemon.
• Pushing to Azure Container Registry is not currently supported.

If a question you have is not answered below, please submit an issue.

See rules_docker for a similar existing container image build tool for the Bazel build system. The tool can build images for languages such as Python, NodeJS, Java, Scala, Groovy, C, Go, Rust, and D.

Jib currently builds into the Docker V2.2 image format or OCI image format. See Extended Usage for the imageFormat configuration.

The plugin attaches a default entrypoint that will run your application automatically.

When running the image, you can override this default entrypoint with your own custom command.

See docker run --entrypoint reference for running the image with Docker and overriding the entrypoint command.

See Define a Command and Arguments for a Container for running the image in a Kubernetes Pod and overriding the entrypoint command.

When running the image, you can pass in additional JVM flags via the JAVA_TOOL_OPTIONS environment variable.

See docker run -e reference for running the image with Docker and setting environment variables.

See Define Environment Variables for a Container for running the image in a Kubernetes Pod and setting environment variables.

Jib packages your Java application into the following paths on the image:

• /app/libs/ contains all the dependency artifacts
• /app/resources/ contains all the resource files
• /app/classes/ contains all the classes files

Running commands like apt-get slows down the container build process. We do not recommend or support running commands as part of the build.

However, if you need to run commands, you can build a custom base image. You can then use this custom base image in the jib-maven-plugin by adding the following configuration:

<configuration>
  <from>custom-base-image</from>
</configuration>

We currently do not support adding a custom directory to the image. If your application needs to use custom files, place them into your application's resources directory (src/main/resources by default). These resource files will be available on the classpath.

We currently do not support building to a local Docker daemon. However, this feature is in the pipeline and will be added in the future.

You can still docker pull the image built with jib-maven-plugin to have it available in your local Docker daemon.

You can also run a local Docker registry and point Jib to push to the local registry.

When you use your private image built with Jib in a Kubernetes cluster, the cluster needs to be configured with credentials to pull the image. This involves 1) creating a Secret, and 2) using the Secret as imagePullSecrets.

kubectl create secret docker-registry registry-json-key \
  --docker-server=<registry> \
  --docker-username=<username> \
  --docker-password=<password> \
  --docker-email=<any valid email address>

kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"registry-json-key"}]}'

For example, if you are using GCR, the commands would look like (see Advanced Authentication Methods):

kubectl create secret docker-registry gcr-json-key \
  --docker-server=https://gcr.io \
  --docker-username=_json_key \
  --docker-password="$(cat keyfile.json)" \
  [email protected]

kubectl patch serviceaccount default \
  -p '{"imagePullSecrets":[{"name":"gcr-json-key"}]}'

See more at Using Google Container Registry (GCR) with Minikube.

TODO: Provide solution.

TODO: Provide solution.

To tag the image with a simple timestamp, add the following to your pom.xml:

<properties>
  <maven.build.timestamp.format>yyyyMMdd-HHmmssSSS</maven.build.timestamp.format>
</properties>

Then in the jib-maven-plugin configuration, set the tag to:

<configuration>
  <tag>${maven.build.timestamp}</tag>
</configuration>

You can then use the same timestamp to reference the image in other plugins.

• Chat with us on gitter
• jib-users mailing list