jib-core

Jib Core - Java library for building containers

Jib Core is a Java library for building Docker and OCI container images. It implements a general-purpose container builder that can be used to build containers without a Docker daemon, for any application. The implementation is pure Java.

The API is currently in alpha and may change substantially.

Jib Core powers the popular Jib plugins for Maven and Gradle. The plugins build containers specifically for JVM languages and separate the application into multiple layers to optimize for fast rebuilds.
For the Maven plugin, see the jib-maven-plugin project.
For the Gradle plugin, see the jib-gradle-plugin project.

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

Upcoming features

• Extensions to make building Java and other language-specific containers easier
• Structured events to react to parts of Jib Core's execution

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

Adding Jib Core to your build

Add Jib Core as a dependency using Maven:

<dependency>
  <groupId>com.google.cloud.tools</groupId>
  <artifactId>jib-core</artifactId>
  <version>0.1.0</version>
</dependency>

Add Jib Core as a dependency using Gradle:

dependencies {
  compile 'com.google.cloud.tools:jib-core:0.1.0'
}

Simple example

Jib.from("busybox")
   .addLayer(Arrays.asList(Paths.get("helloworld.sh")), AbsoluteUnixPath.get("/")) 
   .setEntrypoint("sh", "/helloworld.sh")
   .containerize(
       Containerizer.to(RegistryImage.named("gcr.io/my-project/hello-from-jib")
                                     .addCredential("myusername", "mypassword")));

1. Jib.from("busybox") creates a new JibContainerBuilder configured with busybox as the base image.
2. .addLayer(...) configures the JibContainerBuilder with a new layer with helloworld.sh (local file) to be placed into the container at /helloworld.sh.
3. .setEntrypoint("sh", "/helloworld.sh") sets the entrypoint of the container to run /helloworld.sh.
4. RegistryImage.named("gcr.io/my-project/hello-from-jib") creates a new RegistryImage configured with gcr.io/my-project/hello-from-jib as the target image to push to.
5. .addCredential adds the username/password credentials to authenticate the push to gcr.io/my-project/hello-from-jib. See CredentialRetrieverFactory for common credential retrievers (to retrieve credentials from Docker config or credential helpers, for example). These credential retrievers an be used with .addCredentialRetriever.
6. Containerizer.to creates a new Containerizer configured to push to the RegistryImage.
7. .containerize executes the containerization. If successful, the container image will be available at gcr.io/my-project/hello-from-jib.

Tutorials

None yet available. We welcome contributions for examples and tutorials!

API overview

Jib - the main entrypoint for using Jib Core

JibContainerBuilder - configures the container to build

Containerizer - configures how and where to containerize to

JibContainer - information about the built container

Three TargetImage types define the 3 different targets Jib can build to:

• RegistryImage - builds to a container registry
• DockerDaemonImage - builds to a Docker daemon
• TarImage - saves as a tarball archive

Other useful classes:

• ImageReference - represents an image reference and has useful methods for parsing and manipulating image references
• LayerConfiguration - configures a container layer to build
• CredentialRetriever - implement with custom credential retrieval methods for authenticating against a container registry
• CredentialRetrieverFactory - provides useful CredentialRetrievers to retrieve credentials from Docker config and credential helpers
• EventHandlers - attach event handlers to handle events dispatched during the container build execution

API reference

API reference

How Jib Core works

The Jib Core system consists 3 main parts:

• an execution orchestrator that executes an asynchronous pipeline of containerization steps,
• an image manipulator capable of handling Docker and OCI image formats, and
• a registry client that implements the Docker Registry V2 API.

Some other parts of Jib Core internals include:

• a caching mechanism to speed up builds (configurable with Containerizer.setApplicationLayersCache and Containerizer.setBaseImageLayersCache)
• an eventing system to react to events from Jib Core during its execution (add handlers with Containerizer.setEventHandlers)
• support for fully-concurrent multi-threaded executions

How Jib Works

See the Jib project README.

Frequently Asked Questions (FAQ)

See the Jib project FAQ.

Community

See the Jib project README.