JVM Containers

Elide comes with a built-in containerization tool.

It is exposed in two ways.

Drop-in usage — elide jib -- [OPTION...] passes arguments directly to the built-in jib tool.
Build system integration — elide build creates containers automatically based on declarations in elide.pkl.

Drop-in Usage

Drop-in usage is called via elide jib -- that acts identically to normal jib.

elide jib invocations use the following format:

shell

 elide jib -- < jib options> <source files>

-- separates Elide and jib-specific options.

Note

There are no Elide-specific options before -- at this time. The -- separator is still required.

Elide Jib supports three subcommands for containerizing different artifact types.

Command	Description
`build`	Build a container.
`jar`	Containerize a jar.

| war | Containerize a war. |

For more information about Jib, see here.

Build Command

The build command creates a container image from a Jib YAML build file.

shell

 elide jib -- build -t < target-image> -b < build-file> [options]

Flag	Description
`-t`, `—target=IMAGE`	The destination image reference or Jib-style URL (required).
`-b`, `—build-file=PATH`	Path to the build file (default: `jib.yaml`).
`-c`, `—context=DIR`	The context root directory of the build.
`—name=IMAGE`	The image reference to inject into the tar configuration (required when using `tar://`).
`-p`, `—parameter=NAME=VALUE`	Templating parameter to inject into build file (repeatable).
`—additional-tags=TAG[,TAG...]`	Additional tags for target image.
`—base-image-cache=DIR`	Path to a base image cache.
`—project-cache=DIR`	Path to the project cache.
`—image-metadata-out=PATH`	Path to JSON file for image metadata after build.
`—verbosity=LEVEL`	Set logging verbosity: quiet, error, warn, lifecycle, info, debug (default: lifecycle).
`—console=TYPE`	Set console output type: auto, rich, plain (default: auto).
`—allow-insecure-registries`	Allow communication with registries over HTTP.
`—send-credentials-over-http`	Allow sending credentials over HTTP.

Target Formats

The --target flag accepts several URL schemes.

Format	Description
`registry://IMAGE`	Push to a container registry
`docker://IMAGE`	Load into local Docker daemon
`tar://PATH`	Write to a tar archive (requires `—name`)
`gcr.io/project/image`	Push directly to a registry by reference

Authentication Options

Credentials can be provided in several ways.

Flag	Description
`—credential-helper=HELPER`	Credential helper for both registries
`—username=USER`	Username for both registries
`—password=PASS`	Password for both registries
`—from-credential-helper=HELPER`	Credential helper for base image registry
`—from-username=USER`	Username for base image registry
`—from-password=PASS`	Password for base image registry
`—to-credential-helper=HELPER`	Credential helper for target registry
`—to-username=USER`	Username for target registry
`—to-password=PASS`	Password for target registry

Build File Format

Jib uses a YAML build file to define the container image. To learn more about jib.yaml, refer to jib-cli GitHub page.

Build Usage Example

Given a project with a jib.yaml build file, you can build a container and load it into Docker.

shell

 elide jib -- build -t docker://my-app:latest -b jib.yaml

To build and write to a tar archive instead:

shell

 elide jib -- build -t tar://my-app.tar --name my-app:latest -b jib.yaml

To push to a remote registry:

shell

 elide jib -- build -t registry://gcr.io/my-project/my-app:latest -b jib.yaml

Jar Command

The jar command containerizes an existing JAR file directly, without a build file.

shell

 elide jib -- jar -t < target-image> [options] < jar-file>

Jar Usage Example

To containerize a JAR and load it into Docker:

shell

 elide jib -- jar -t docker://my-app:latest --from eclipse-temurin:25-jre app.jar

Build System Integration

When using elide build with an elide.pkl project file, container image builds can be declared as artifacts and built automatically.

Declaring Container Images

Container images are declared in the artifacts block of your elide.pkl using the ContainerImage type from elide:Container.pkl. The container requires a valid source and a JVM package to be declared.

pkl

amends "elide:project.pkl"
import "elide:Sources.pkl" as Sources
import "elide:Container.pkl" as Container
import "elide:Jvm.pkl" as Jvm

sources {
   ["main"] = new Sources.SourceSetSpec {
      paths {
        "./src/HelloWorld.java"
     }
   }
}

jvm {
   main = "dev.main"
}

artifacts {
   ["main-jvm"] = new Jvm.Jar {
     sources {
      "main"
     }
    }
   ["container"] = new Container.ContainerImage {
      from {
      "main-jvm"
      }
      output = "daemon"
  }
}

Container Image Properties

Property	Type	Default	Description
`from`	`Listing<String>`	`{}`	Artifact names from which to build the container image
`image`	`String?`	—	Target image coordinate
`base`	`String?`	—	Base image to use for the container
`tags`	`Listing<String>`	`{}`	Tags to apply to the container image
`output`	`ContainerOutputMode`	`"daemon"`	Output mode: `daemon`, `registry`, or `tarball`
`format`	`ContainerFormat`	`"docker"`	Image format: `docker` or `oci`

Output Modes

The output property controls where the built container image is published.

Mode	Description
`daemon`	Publish to the local Docker daemon
`registry`	Push directly to the registry specified in the image coordinate
`tarball`	Write to a local tarball that can be imported manually into Docker

Image Formats

Format	Description
`docker`	Docker Image
`oci`	Open Container Initiative (OCI) image format

Build System Usage Example

Given the following elide.pkl:

pkl

amends "elide:project.pkl"
import "elide:Sources.pkl" as Sources
import "elide:Jvm.pkl" as Jvm
import "elide:Container.pkl" as Container

sources {
  ["main"] = new Sources.SourceSetSpec {
    paths {
      "src/main/java<<>>*.java"
    }
  }
}

artifacts {
  ["app-jar"] = new Jvm.Jar {
    from { "main" }
  }

  ["app-image"] = new Container.ContainerImage {
    from { "app-jar" }
    image = "my-app"
    base = "eclipse-temurin:25-jre"
    tags { "latest" }
    output = "daemon"
  }
}

Running elide build will compile sources, package the JAR, and build the container image automatically.