Runtime & JVM

Container images with Google Jib

This guide explains how to create a container image for a Vert.x application using Google Jib.

Unlike the Dockerfile approach, Jib builds optimized, layered OCI-compliant images (Docker images) directly from your build tool, without needing a Docker daemon (unless you are building to your local daemon) or a Dockerfile.

Besides, Jib significantly reduces build times by separating your application into distinct layers (dependencies, resources, and classes), allowing it to rebuild and push only the specific layers that have changed rather than the entire image.

What you will build

You will create a Vert.x application and build a container image for it using the Jib plugin. You will then run this image using Docker.

What you need

A text editor or IDE
Java 11 or higher
Docker (only required to run the image locally)
Maven or Gradle

Maven

This section describes how to use Google Jib with Maven.

Generate the project

Open your browser to https://start.vertx.io.
Select Maven build tool.
Set layered-container-jib as artifactId.
Select JDK 11 or higher.
Click Generate Project to download the project archive.
Unzip the archive into a folder.

Alternatively, open a terminal and run:

curl -G https://start.vertx.io/starter.zip -d "artifactId=layered-container-jib" -d "jdkVersion=11" -d "buildTool=maven" --output layered-container-jib.zip
unzip layered-container-jib.zip

Or, with HTTPie:

http https://start.vertx.io/starter.zip artifactId==layered-container-jib jdkVersion==11 buildTool==maven --output layered-container-jib.zip
unzip layered-container-jib.zip

Configure the build

Open the pom.xml file. You need to add the jib-maven-plugin to the <plugins> section.

You must configure two main things:

The Base Image (from): We will use a standard JDK image.
The Entrypoint (container): Since Jib explodes the classpath (it doesn’t build a fat jar), we explicitly run the Vert.x Launcher and pass your verticle as an argument.

Add the following to your pom.xml:

Jib Maven Plugin

      <plugin>
        <groupId>com.google.cloud.tools</groupId>
        <artifactId>jib-maven-plugin</artifactId>
        <version>3.4.4</version>
        <configuration>
          <from>
            <image>eclipse-temurin:11-jre</image> (1)
          </from>
          <to>
            <image>layered-container-jib</image> (2)
          </to>
          <container>
            <mainClass>io.vertx.launcher.application.VertxApplication</mainClass> (3)
            <args>
              <arg>${main.verticle}</arg> (4)
            </args>
            <ports>
              <port>8888</port> (5)
            </ports>
          </container>
        </configuration>
      </plugin>

1	The base image. We use `eclipse-temurin:11-jre` to keep the image size small.
2	The name of the image being built.
3	The main class to run: the Vert.x Launcher.
4	The arguments passed to the launcher: the name of your main verticle (defined in properties).
5	The port the container exposes (matches the HTTP server port).

Build the container image

You can now build the container image.

If you want to build the image and save it directly to your local Docker daemon (so you can run it immediately with docker run), use the specific dockerBuild goal.

mvn compile jib:dockerBuild

If you want to push the image directly to a registry (like Docker Hub) without needing Docker running on your machine, you would use mvn compile jib:build. You will need to configure registry authentication for this.

Run the application

Now that the image is built and available in your local Docker daemon, you can run it.

docker run -t -i -p 8888:8888 layered-container-jib

You should see the Vert.x startup logs:

HTTP server started on port 8888
INFO: Succeeded in deploying verticle

You can now test the application by opening your browser to http://localhost:8888.

Gradle

This section describes how to use Google Jib with Gradle (Kotlin DSL).

Generate the project

Open your browser to https://start.vertx.io.
Select Gradle build tool.
Set jib-gradle-howto as artifactId.
Select JDK 11 or higher.
Click Generate Project to download the project archive.
Unzip the archive into a folder.

Alternatively, open a terminal and run:

curl -G https://start.vertx.io/starter.zip -d "artifactId=layered-container-jib" -d "jdkVersion=11" -d "buildTool=gradle" --output layered-container-jib.zip
unzip layered-container-jib.zip

Or, with HTTPie:

http https://start.vertx.io/starter.zip artifactId==layered-container-jib jdkVersion==11 buildTool==gradle --output layered-container-jib.zip
unzip layered-container-jib.zip

Configure the build

Open the build.gradle.kts file.

First, you need to define the Jib plugin.

Jib Gradle Plugin Definition

plugins {
  java
  application
  id("com.github.johnrengelman.shadow") version "8.1.1"
  id("com.google.cloud.tools.jib") version "3.4.4" (1)
}

1	The Jib Gradle Plugin

Then you need to apply the Jib plugin and configure the container entry point.

Jib Gradle Plugin Configuration

jib {
  from {
    image = "eclipse-temurin:11-jre" (1)
  }
  to {
    image = "layered-container-jib" (2)
  }
  container {
    mainClass = launcherClassName (3)
      args = listOf(mainVerticleName) (4)
      ports = listOf("8888") (5)
  }
}

1	The base image. We use `eclipse-temurin:11-jre` to keep the image size small.
2	The name of the image being built.
3	The main class to run: the Vert.x Launcher.
4	The arguments passed to the launcher: the name of your main verticle (defined in properties).
5	The port the container exposes (matches the HTTP server port).

Build the container image

You can now build the container image.

If you want to build the image and save it directly to your local Docker daemon (so you can run it immediately with docker run), use the specific jibDockerBuild task.

./gradlew jibDockerBuild

If you want to push the image directly to a registry (like Docker Hub) without needing Docker running on your machine, you would use ./gradlew jibBuild. You will need to configure registry authentication for this.

Run the application

Now that the image is built and available in your local Docker daemon, you can run it.

docker run -t -i -p 8888:8888 layered-container-jib

You should see the Vert.x startup logs:

HTTP server started on port 8888
INFO: Succeeded in deploying verticle

You can now test the application by opening your browser to http://localhost:8888.

Summary

This document covered:

configuring the Google Jib plugin for Maven,
configuring the Google Jib plugin for Gradle.