Building OCI Images with Spring Boot
Spring Boot supports building OCI images with Maven and Gradle plugins. This is accomplished through integration with Cloud Native Buildpacks (CNB). See the Maven and Gradle documentation for details.
Building images requires access to a Docker-compatible daemon over a socket or an HTTP(S) connection. The daemon must be accessible by the build plugins running locally and by processes that run inside a CNB container This page provides tips and additional information for setting up and troubleshooting the infrastructure required for building images.
Podman is an alternative to Docker Engine. Spring Boot supports building images using Podman, providing Podman is configured in a compatible way. The following sections contain tips for configuring and troubleshooting Podman integration.
The documentation for the Spring Boot Maven and Gradle plugins include information on configuring the plugins to use the Podman daemon instead of the Docker daemon.
The availability of the Podman socket as documented depends on the installation method used, and it is difficult to document all possible situations. See the following Podman documentation for additional steps that might be required after installation:
The results of the command podman info --format='{{.Host.RemoteSocket.Path}}' shown in the Spring Boot build plugins documentation for getting the socket to use is reliable on Linux, but might not be reliable on Windows or macOS.
The user running the Spring Boot build plugins must have permissions to read from and write to the Podman socket. In addition, processes running inside the CNB builder container must have permissions to access the socket.
Podman Desktop is a product that builds on the Podman daemon.
It provides a graphical user interface and additional features, including a Docker compatibility mode that creates a symbolic link from the Podman socket to the typical Docker socket location at /var/run/docker.sock.
Depending on the platform and the installation method, the socket symlink created for Docker compatibility might not have the permissions needed for the CNB builder container.
It is recommended that the Spring Boot build plugins are configured to use the Podman socket directly instead of relying on the Docker compatibility mode.
The podman-mac-helper is recommended when using Podman Desktop on macOS.
The Spring Boot plugins will pull two images that are required to run buildpacks. By default, Paketo builder and run images will be used. When the images are successfully pulled, the build plugins should show output similar to this:
> Pulling builder image 'docker.io/paketobuildpacks/builder-jammy-base:latest' ..................................................
> Pulled builder image 'docker.io/paketobuildpacks/builder-jammy-base@sha256:aeb263786ab12e5da2f634f1cdc79cac260da3a76cca106046a1746e93e4ce52'
> Pulling run image 'docker.io/paketobuildpacks/run-jammy-base:latest' ..................................................
> Pulled run image 'docker.io/paketobuildpacks/run-jammy-base@sha256:8431203470391fc58454b71bdb917f53c20f403892fbb447f4ea5265a8d7cf49'
If errors occur when pulling these images, try pulling them manually to ensure the Docker daemon is running properly.
With the Docker CLI:
docker pull docker.io/paketobuildpacks/builder-jammy-base:latest
docker pull docker.io/paketobuildpacks/run-jammy-base:latest
With the Podman CLI:
podman pull docker.io/paketobuildpacks/builder-jammy-base:latest
podman pull docker.io/paketobuildpacks/run-jammy-base:latest
The pack CLI can be used to build images using CNB.
It can be useful to try building images with pack instead of with the Spring Boot build plugins to diagnose problems with the local setup.
Buildpacks can build images from source code or from a built jar or war file.
The Spring Boot plugins always provide jar or war contents to the builder, so the jar or war file should also be provided when testing for compatibility with pack.
Given an a project named myproject built with Gradle, the pack command would be:
pack build --builder paketobuildpacks/builder-jammy-base:latest --path build/libs/myproject-0.0.1-SNAPSHOT.jar myproject
If the project is built with Maven, the pack command would be:
pack build --builder paketobuildpacks/builder-jammy-base:latest --path target/myproject-0.0.1-SNAPSHOT.jar myproject
The pack build command has options similar to those supported by the Spring Boot Maven and Gradle plugins.