gradle-docker-jib

Gradle Docker Jib Integration

Table of Contents

• Purpose
• When to Use
• Quick Start
• Instructions
• Requirements
• See Also

Purpose

Build Docker images efficiently using Google's Jib plugin without requiring Docker installation, Dockerfiles, or container knowledge. Jib automatically optimizes layers and handles multi-architecture builds for local and registry deployments.

When to Use

Use this skill when you need to:

• Build Docker images without Docker daemon or Dockerfiles
• Containerize Spring Boot microservices efficiently
• Create multi-architecture images (amd64, arm64) for cloud deployment
• Optimize Docker layer caching for faster builds
• Push images to GCR, Docker Hub, or private registries
• Integrate Docker image building in CI/CD pipelines

Quick Start

Add Jib plugin to build.gradle.kts:

plugins {
    id("com.google.cloud.tools.jib") version "3.4.4"
}

jib {
    from {
        image = "eclipse-temurin:21-jre-alpine"
    }
    to {
        image = "gcr.io/my-project/my-app"
        tags = setOf("latest", project.version.toString())
    }
    container {
        jvmFlags = listOf("-Xmx512m", "-Xms256m")
        ports = listOf("8080")
        user = "nobody"
    }
}

Build to local Docker:

./gradlew jibDockerBuild

Build and push to registry:

./gradlew jib

Instructions

Step 1: Add Jib Plugin

Add to build.gradle.kts:

plugins {
    id("com.google.cloud.tools.jib") version "3.4.4"
}

Or in build.gradle:

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

Step 2: Configure Base Image

Choose appropriate base image:

For Spring Boot (JRE only):

jib {
    from {
        image = "eclipse-temurin:21-jre-alpine"
        // or for ARM support
        // image = "eclipse-temurin:21-jre"
    }
}

For distroless (minimal):

jib {
    from {
        image = "gcr.io/distroless/java21-debian12"
    }
}

See references/detailed-guide.md for base image selection guide.

Step 3: Configure Target Registry

Google Container Registry (GCR):

jib {
    to {
        image = "gcr.io/my-project/my-app"
        tags = setOf("latest", project.version.toString())
    }
}

Docker Hub:

jib {
    to {
        image = "docker.io/myusername/my-app"
        auth {
            username = System.getenv("DOCKER_USERNAME")
            password = System.getenv("DOCKER_PASSWORD")
        }
    }
}

Private registry:

jib {
    to {
        image = "registry.company.com/my-app"
        credHelper = "gcr"  // or "ecr-login", "docker-credential-gcr"
    }
}

Step 4: Configure Container Settings

JVM flags and ports:

jib {
    container {
        jvmFlags = listOf(
            "-Xmx512m",
            "-Xms256m",
            "-Dspring.profiles.active=prod",
            "-XX:+UseContainerSupport"
        )
        ports = listOf("8080", "8081")
        labels = mapOf(
            "maintainer" to "team@company.com",
            "version" to project.version.toString()
        )
        user = "nobody"
        workingDirectory = "/app"
    }
}

Environment variables:

jib {
    container {
        environment = mapOf(
            "PORT" to "8080",
            "ENV" to "production"
        )
    }
}

See references/detailed-guide.md for advanced container configuration.

Step 5: Configure Multi-Architecture Images

Build for multiple platforms:

jib {
    from {
        image = "eclipse-temurin:21-jre"
        platforms {
            platform {
                architecture = "amd64"
                os = "linux"
            }
            platform {
                architecture = "arm64"
                os = "linux"
            }
        }
    }
}

Step 6: Set Up Authentication

Using credential helpers:

# Install credential helper
gcloud auth configure-docker

# Or for Docker Hub
docker login

Using environment variables:

export DOCKER_USERNAME=myuser
export DOCKER_PASSWORD=mypassword
./gradlew jib

In CI/CD:

# GitHub Actions
- name: Build and Push
  run: ./gradlew jib
  env:
    DOCKER_USERNAME: ${{ secrets.DOCKER_USERNAME }}
    DOCKER_PASSWORD: ${{ secrets.DOCKER_PASSWORD }}

Step 7: Build Images

Build to local Docker daemon:

./gradlew jibDockerBuild
docker images  # Verify image exists

Build and push to registry:

./gradlew jib

Build OCI tar archive:

./gradlew jibBuildTar
# Creates build/jib-image.tar

Step 8: Configure Multi-Module Projects

For multi-module projects, configure Jib in specific modules:

// app/build.gradle.kts
plugins {
    id("com.google.cloud.tools.jib")
}

jib {
    to {
        image = "gcr.io/my-project/${project.name}"
    }
    container {
        mainClass = "com.example.app.MainKt"
    }
}

// service-a/build.gradle.kts
plugins {
    id("com.google.cloud.tools.jib")
}

jib {
    to {
        image = "gcr.io/my-project/${project.name}"
    }
}

See references/detailed-guide.md for complete multi-module setup.

Step 9: Optimize Build Performance

Enable caching:

jib {
    // Use timestamp for better layer caching
    container {
        creationTime = "USE_CURRENT_TIMESTAMP"
    }
}

Skip unchanged layers: Jib automatically caches layers by content hash - no configuration needed.

Requirements

• Gradle: 7.0+ (8.11+ recommended)
• Java: JDK 11+ (21 recommended)
• Jib Plugin: 3.4.4+
• Authentication:
  • Docker credential helper (recommended)
  • Environment variables
  • Docker config (~/.docker/config.json)
• For Local Docker:
  • Docker daemon running
  • jibDockerBuild command
• For Registry Push:
  • Valid credentials
  • Network access to registry

See Also

• references/detailed-guide.md - Comprehensive examples, commands reference, troubleshooting, and best practices
• gradle-ci-cd-integration - Integrate Jib in CI/CD pipelines
• Jib Documentation - Official Jib docs