Jib CLI

jib is a general-purpose command-line utility for building Docker or OCI container images from file system content as well as JAR files. Jib CLI builds containers fast and reproducibly without Docker like other Jib tools.

# docker not required
$ docker
-bash: docker: command not found
# build and upload an image
$ jib build --target=my-registry.example.com/built-by-jib

Additionally, Jib CLI can directly build an optimized image for JAR files (including Spring Boot fat JAR).

$ jib jar --target=my-registry.example.com/jar-app myapp.jar

The CLI tool is powered by Jib Core, a Java library for building containers without Docker.

Get the Jib CLI

Most users should download a ZIP archive (Java application). We are working on releasing a native executable binary using GraalVM. (Help wanted!)

Download a Java Application

A JRE is required to run this Jib CLI distribution.

Find the latest jib-cli 0.8.0 release on the Releases page, download jib-jre-<version>.zip, and unzip it. The zip file contains the jib (jib.bat for Windows) script at jib/bin/. Optionally, add the binary directory to your $PATH so that you can call jib from anywhere.

Windows: Install with `choco`

On Windows, you can use the choco command. To install, upgradle, or uninstall Jib CLI, run the following commands from the command-line or PowerShell:

choco install jib
choco upgrade jib
choco uninstall jib

Build Yourself from Source (for Advanced Users)

Use the application plugin's installDist task to create a runnable installation in build/install/jib. A zip and tar file are also created in build/distributions.

# build
$ ./gradlew jib-cli:installDist
# run
$ ./jib-cli/build/install/jib/bin/jib

Supported Commands

The Jib CLI supports two commands:

build - containerizes using a build file.
jar - containerizes JAR files.
war - containerizes WAR files.

Build Command

This command follows the following pattern:

jib build --target <image name> [options]

Quickstart

Create a hello world script (script.sh) containing:
```
#!/bin/sh
echo "Hello World"
```

Create a build file. The default is a file named jib.yaml in the project root.

apiVersion: jib/v1alpha1
kind: BuildFile

from:
  image: ubuntu

entrypoint: ["/script.sh"]

layers:
  entries:
    - name: scripts
      files:
        - properties:
            filePermissions: 755
          src: script.sh
          dest: /script.sh

Build to docker daemon

 $ jib build --target=docker://jib-cli-quickstart

Run the container

 $ docker run jib-cli-quickstart
 Hello World

Options

Optional flags for the build command:

Option	Description
`-b, --build-file`	The path to the build file (ex: path/to/other-jib.yaml)
`-c, --context`	The context root directory of the build (ex: path/to/my/build/things)
`-p, --parameter`	Templating parameter to inject into build file, replace ${} with (repeatable)

Jar Command

This command follows the following pattern:

jib jar --target <image name> path/to/myapp.jar [options]

Quickstart

Have your JAR (thin or fat) ready. We will be using the Spring Petclinic JAR in this Quickstart.

 $ git clone https://github.com/spring-projects/spring-petclinic.git
 $ cd spring-petclinic
 $ ./mvnw package

Containerize your JAR using the jar command. In the default mode (exploded), the entrypoint will be set to java -cp /app/dependencies/:/app/explodedJar/ HelloWorld
```
 $ jib jar --target=docker://cli-jar-quickstart target/spring-petclinic-*.jar
```
Run the image and open your browser at http://localhost:8080
```
 $ docker run -p 8080:8080 cli-jar-quickstart
```

Options

Optional flags for the jar command:

Option	Description
`--jvm-flags`	JVM arguments, example: `--jvm-flags=-Dmy.property=value,-Xshare:off`
`--mode`	The jar processing mode, candidates: exploded, packaged, default: exploded

War Command

This command follows the following pattern:

 $ jib war --target <image-name> path/to/myapp.war

Quickstart

Have your sample WAR ready and use the war command to containerize your WAR. By default, the WAR command uses jetty as the base image so the entrypoint is set to java -jar /usr/local/jetty/start.jar:
```
 $ jib war --target=docker://cli-war-quickstart <your-sample>.war
```
Run the image and open your browser at http://localhost:8080
```
 $ docker run -p 8080:8080 cli-war-quickstart
```

Options

Flags for the war command:

Option	Description
`--app-root`	The app root on the container. Customizing the app-root is helpful if you are using a different Servlet engine base image (for example, Tomcat)

Options Shared Between the Jar and War Commands

Here are a few container configurations that can be customized when using the jar and war commands.

Option	Description
`--creation-time`	The creation time of the container in milliseconds since epoch or iso8601 format. Overrides the default (1970-01-01T00:00:00Z)
`--entrypoint`	Entrypoint for container. Overrides the default entrypoint, example: `--entrypoint='custom entrypoint'`
`--environment-variables`	Environment variables to write into container, example: `--environment-variables env1=env_value1, env2=env_value2`.
`--expose`	Ports to expose on container, example: `--expose=5000,7/udp`.
`--from`	The base image to use.
`--image-format`	Format of container, candidates: Docker, OCI, default: Docker.
`--labels`	Labels to write into container metadata, example: `--labels=label1=value1,label2=value2`.
`--program-args`	Program arguments for container entrypoint.
`-u, --user`	The user to run the container as, example: `--user=myuser:mygroup`.
`--volumes`	Directories on container to hold extra volumes, example: `--volumes=/var/log,/var/log2`.

Common Jib CLI Options

The options can either be specified in the command line or defined in a configuration file:

[@<filename>...]      One or more argument files containing options.

Auth/Security

    --allow-insecure-registries            Allow jib to send credentials over http (insecure)
    --send-credentials-over-http           Allow jib to send credentials over http (very insecure)

Registry Credentials

Credentials can be specified using credential helpers or username + password. The following options are available:

    --credential-helper <credHelper>      credential helper for communicating with both target and base image registries, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>`
    --to-crendential-helper <credHelper>  credential helper for communicating with target registry, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>
    --from-credential-helper <credHelper> credential helper for communicating with base image registry, either a path to the helper, or a suffix for an executable named `docker-credential-<suffix>`

    --username <username>                  username for communicating with both target and base image registries
    --password <password>                  password for communicating with both target and base image registries
    --to-username <username>               username for communicating with target image registry
    --to-password <password>               password for communicating with target image registry
    --from-username <username>             username for communicating with base image registry
    --from-password <password>             password for communicating with base image registry

Note - Combinations of credential-helper, username and password flags come with restrictions and can be use only in the following ways:

Only Credential Helper

--credential-helper
--to-credential-helper
--from-credential-helper
--to-credential-helper, --from-credential-helper

Only Username and Password

--username, --password
--to-username, --to-password
--from-username, --from-password
--to-username, --to-password, --from-username, --from-password

Mixed Mode

--to-credential-helper, --from-username, --from-password
--from-credential-helper, --to-username, --to-password

Info Params

    --help                  print usage and exit
    --console <type>        set console output type, candidates: auto, rich, plain, default: auto
    --verbosity <level>     set logging verbosity, candidates: quiet, error, warn, lifecycle, info, debug, default: lifecycle
-v, --version               Jib CLI version information

Debugging Params

    --stacktrace            print stacktrace on error (for debugging issues in the jib-cli)
    --http-trace            enable http tracing at level=config, output=console
    --serialize             run jib in serialized mode

Global Jib Configuration

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/Config/ if not set)
Windows: [config root]\Google\Jib\Config\config.json, where [config root] is $XDG_CONFIG_HOME (%LOCALAPPDATA% if not set)

Properties

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

References

Fully Annotated Build File (`jib.yaml`)

# required apiVersion and kind, for compatibility over versions of the cli
apiVersion: jib/v1alpha1
kind: BuildFile

# full base image specification with detail for manifest lists or multiple architectures
from:
  image: "ubuntu"
  # set platforms for multi architecture builds, defaults to `linux/amd64`
  platforms:
    - architecture: "arm"
      os: "linux"
    - architecture: "amd64"
      os: "darwin"

# creation time sets the creation time of the container only
# can be: millis since epoch (ex: 1000) or an ISO 8601 creation time (ex: 2020-06-08T14:54:36+00:00)
creationTime: 2000

format: Docker # Docker or OCI

# container environment variables
environment:
  "KEY1": "v1"
  "KEY2": "v2"
  
# container labels
labels:
  "label1": "l1"
  "label2": "l2"
  
# specify volume mount points
volumes:
  - "/volume1"
  - "/volume2"

# specify exposed ports metadata (port-number/protocol)
exposedPorts:
  - "123/udp"
  - "456"      # default protocol is tcp
  - "789/tcp"

# the user to run the container (does not affect file permissions)
user: "customUser"

workingDirectory: "/home"

entrypoint:
  - "sh"
  - "script.sh"
cmd:
  - "--param"
  - "param"

# file layers of the container
layers: 
  properties:                        # file properties applied to all layers
    filePermissions: "123"           # octal file permissions, default is 644
    directoryPermissions: "123"      # octal directory permissions, default is 755
    user: "2"                        # default user is 0
    group: "4"                       # default group is 0
    timestamp: "1232"                # timestamp can be millis since epoch or ISO 8601 format, default is "Epoch + 1 second"
  entries:
    - name: "scripts"                # first layer
      properties:                    # file properties applied to only this layer
        filePermissions: "123"           
        # see above for full list of properties...
      files:                         # a list of copy directives constitute a single layer
        - src: "project/run.sh"      # a simple copy directive (inherits layer level file properties)
          dest: "/home/run.sh"       # all 'dest' specifications must be absolute paths on the container
        - src: "scripts"             # a second copy directive in the same layer
          dest: "/home/scripts"
          excludes:                  # exclude all files matching these patterns
            - "**/exclude.me"
            - "**/*.ignore"
          includes:                  # include only files matching these patterns
            - "**/include.me"            
          properties:                # file properties applied to only this copy directive
            filePermissions: "123"           
            # see above for full list of properties...  
    - name: "images"                 # second layer, inherits file properties from global
      files:
        - src: "images"
        - dest: "/images"

Layers Behavior

Copy directives are bound by the following rules src: filetype determined by type on local disk
- if src is directory, dest is always considered a directory, directory and contents will be copied over and renamed to dest
- if src is file
  - if dest ends with / then it is considered a target directory, file will be copied into directory
  - if dest doesn't end with / then is is the target file location, src file will be copied and renamed to dest
Permissions for a file or directory that appear in multiple layers will prioritize the last layer and copy directive the file appears in. In the following example, file.txt as seen on the running container will have filePermissions 234.
```
- name: layer1
  properties:
    filePermissions: "123"
  - src: file.txt
    dest: /file.txt
- name: layer2
  properties:
    filePermissions: "234"
  - src: file.txt
    dest: /file.txt
```
Parent directories that are not exiplicitly defined in a layer will the default properties in jib-core (permissions: 755, modification-time: epoch+1). In the following example, /somewhere on the container will have the directory permissions 755, not 777 as some might expect.
```
- name: layer
  properties:
    directoryPermissions: "777"
  - src: file.txt
    dest: /somewhere/file.txt
```
excludes on a directory can lead to unintended inclusion of files in the directory, to exclude a directory and all its files
```
excludes:
  - "**/exclude-dir"
  - "**/exclude-dir/**
```

Base Image Parameter Inheritance

Some values defined in the base image may be preserved and propogated into the new container.

Parameters will append to base image value:

volumes
exposedPorts

Parameters that will append any new keys, and overwrite existing keys:

labels
environment

Parameters that will be overwritten:

user
workingDirectory
entrypoint
cmd

Privacy

See the Privacy page.

Disclaimer

This is not an officially supported Google product.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Jib CLI

Table of Contents

Get the Jib CLI

Download a Java Application

Windows: Install with `choco`

Build Yourself from Source (for Advanced Users)

Supported Commands

Build Command

Quickstart

Options

Jar Command

Quickstart

Options

War Command

Quickstart

Options

Options Shared Between the Jar and War Commands

Common Jib CLI Options

Auth/Security

Registry Credentials

Info Params

Debugging Params

Global Jib Configuration

Properties

References

Fully Annotated Build File (`jib.yaml`)

Layers Behavior

Base Image Parameter Inheritance

Privacy

Disclaimer

Files

README.md

Latest commit

History

README.md

File metadata and controls

Jib CLI

Table of Contents

Get the Jib CLI

Download a Java Application

Windows: Install with choco

Build Yourself from Source (for Advanced Users)

Supported Commands

Build Command

Quickstart

Options

Jar Command

Quickstart

Options

War Command

Quickstart

Options

Options Shared Between the Jar and War Commands

Common Jib CLI Options

Auth/Security

Registry Credentials

Info Params

Debugging Params

Global Jib Configuration

Properties

References

Fully Annotated Build File (jib.yaml)

Layers Behavior

Base Image Parameter Inheritance

Privacy

Disclaimer

Windows: Install with `choco`

Fully Annotated Build File (`jib.yaml`)