README.md

beta Gradle Plugin Portal Gitter version

Jib - Containerize your Gradle Java project

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

For information about the project, see the Jib project README. For the Maven plugin, see the jib-maven-plugin project.

Upcoming Features

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

Quickstart

Setup

Make sure you are using Gradle version 4.6 or later.

In your Gradle Java project, add the plugin to your build.gradle:

plugins {
  id 'com.google.cloud.tools.jib' version '0.10.0'
}

See the Gradle Plugin Portal for more details.

You can containerize your application easily with one command:

gradle jib --image=<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:

gradle jibDockerBuild

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

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:

jib.to.image = 'gcr.io/my-gcp-project/my-app'

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:

jib.to.image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-app'

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:

jib.to.image = 'my-docker-id/my-app'

TODO: Add more examples for common registries.

Build Your Image

Build your container image with:

gradle jib

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.

gradle jibDockerBuild

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)
gradle jibDockerBuild

Build an image tarball

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

gradle jibBuildTar

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

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

Run jib with each build

You can also have jib run with each build by attaching it to the build task:

tasks.build.dependsOn tasks.jib

Then, gradle build will build and containerize your application.

Export to a Docker context

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

gradle jibExportDockerContext

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

gradle jibExportDockerContext --jibTargetDir=my/docker/context/

You can then build your image with Docker:

docker build -t myimage my/docker/context/

Additional Build Artifacts

As part of an image build, Jib also writes out the image digest to build/jib-image.digest.

Extended Usage

The plugin provides the jib extension for configuration with the following 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 built image.
extraDirectory extraDirectory / File (project-dir)/src/main/jib Configures the directory used to add arbitrary files to the image.
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.
useProjectOnlyCache boolean false If set to true, Jib does not share a cache between different Maven projects.

from is a closure with the following properties:

Property Type Default Description
image String gcr.io/distroless/java The image reference for the base image.
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 a closure 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 --image 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<String> None Additional tags to push to.

auth is a closure with the following properties (see Using Specific Credentials):

Property Type
username String
password String

container is a closure 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<String> 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.
entrypoint List<String> None The command to start the container with (similar to Docker's ENTRYPOINT instruction). If set, then jvmFlags and mainClass are ignored.
environment Map<String, String> None Key-value pairs for setting environment variables on the container (similar to Docker's ENV instruction).
format String Docker Use OCI to build an OCI container image.
jvmFlags List<String> None Additional flags to pass into the JVM when running your application.
labels Map<String, String> None Key-value pairs for applying image metadata (similar to Docker's LABEL instruction).
mainClass String Inferred* The main class to launch your application from.
ports List<String> None Ports that the container exposes at runtime (similar to Docker's EXPOSE instruction).
useCurrentTimestamp boolean false By default, Jib wipes all timestamps to guarantee reproducibility. If this parameter is set to true, Jib will set the image's creation timestamp to the time of the build, which sacrifices reproducibility for easily being able to tell when your image was created.
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.

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

Property Type
path File
permissions Map<String, String>

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:

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

gradle jibDockerBuild \
    -Djib.container.environment=key1="value1",key2="value2" \
    -Djib.container.args=arg1,arg2,arg3

gradle jibBuildTar -Djib.useProjectOnlyCache=true

You can also configure HTTP connection/read timeouts for registry interactions using the jib.httpTimeout system property, configured in milliseconds via commandline (the default is 20000; you can also set it to 0 for infinite timeout):

gradle jib -Djib.httpTimeout=3000

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

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
jib {
  from {
    image = 'openjdk:alpine'
  }
  to {
    image = 'localhost:5000/my-image/built-with-jib'
    credHelper = 'osxkeychain'
    tags = ['tag2', 'latest']
  }
  container {
    jvmFlags = ['-Xms512m', '-Xdebug', '-Xmy:flag=jib-rules']
    mainClass = 'mypackage.MyApp'
    args = ['some', 'args']
    ports = ['1000', '2000-2003/udp']
    labels = [key1:'value1', key2:'value2']
    format = 'OCI'
  }
}

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 a different directory by using the jib.extraDirectory parameter in your build.gradle:

jib {
  // Copies files from 'src/main/custom-extra-dir' instead of 'src/main/jib'
  extraDirectory = file('src/main/custom-extra-dir')
}

Alternatively, the jib.extraDirectory parameter can be used as a closure to set a custom extra directory, as well as the extra files' permissions on the container:

jib {
  extraDirectory {
    path = file('src/main/custom-extra-dir')  // Copies files from 'src/main/custom-extra-dir'
    permissions = [
        '/path/on/container/to/fileA': '755',  // Read/write/execute for owner, read/execute for group/other
        '/path/to/another/file': '644'  // Read/write for owner, read-only for group/other
    ]
  }
}

Authentication Methods

Pushing/pulling from private registries require authorization credentials. These can be retrieved using Docker credential helpers. 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:

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

Example configuration:

jib {
  from {
    image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image'
    credHelper = 'ecr-login'
  }
  to {
    image = 'gcr.io/my-gcp-project/my-app'
    credHelper = 'gcr'
  }
}

Using Specific Credentials

You can specify credentials directly in the extension for the from and/or to images.

jib {
  from {
    image = 'aws_account_id.dkr.ecr.region.amazonaws.com/my-base-image'
    auth {
      username = USERNAME // Defined in 'gradle.properties'.
      password = PASSWORD
    }
  }
  to {
    image = 'gcr.io/my-gcp-project/my-app'
    auth {
      username = 'oauth2accesstoken'
      password = 'gcloud auth print-access-token'.execute().text.trim()
    }
  }
}

These credentials can be stored in gradle.properties, retrieved from a command (like gcloud auth print-access-token), or read in from a file.

For example, you can use a key file for authentication (for GCR, see Using a JSON key file):

jib {
  to {
    image = 'gcr.io/my-gcp-project/my-app'
    auth {
      username = '_json_key'
      password = file('keyfile.json').text
    }
  }
}

WAR Projects

Jib also containerizes WAR projects. If the Gradle project uses the WAR Plugin, Jib will by default use the distroless Jetty as a base image to deploy the project WAR. No extra configuration is necessary other than using the WAR Plugin to make Jib build WAR images.

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

jib {
  from.image = 'tomcat:8.5-jre8-alpine'

  // 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.
  container.appRoot = '/usr/local/tomcat/webapps/ROOT'
}

How Jib Works

See the Jib project README.

Frequently Asked Questions (FAQ)

See the Jib project FAQ.

Community

See the Jib project README.

Analytics