In this guide you will package an Apache Grails 8 application as a production-ready OCI container image and orchestrate it alongside a real PostgreSQL database with Docker Compose.

The path most teams should pick is Spring Boot 4’s bootBuildImage Gradle task, which delegates to Paketo Buildpacks and produces a minimal, layered, reproducible image with no Dockerfile to maintain. We will lead with that.

For teams that need to control every layer, this guide also covers a hand-rolled multi-stage Dockerfile with a non-root user, and shows how the two paths produce equivalent runtime behaviour.

This guide targets Apache Grails 8 / Spring Boot 4. It supersedes the earlier Grails as a Docker Container guide for Grails 3 and 4, which used the now-deprecated gradle-docker plugin.

By the end of the guide you will have:

The official Grails 8 reference manual at grails-doc/src/en/guide/deployment.adoc (and the deployment/ subdirectory) covers WAR file deployment to a servlet container. This guide complements that by walking the modern OCI-image path that Spring Boot 4’s bootBuildImage task makes possible.

Files touched in this chapter:

To complete this guide you will need:

You can either type the code in this guide as you read or skip ahead and clone the finished sample app:

The repository contains two top-level directories:

Each chapter ends with the file paths it touches relative to the project root, so you can match what you typed against the complete/ reference.

Generate a fresh Apache Grails 8 web application from start.grails.org with the three features the rest of the guide expects: postgres (the JDBC driver and a Postgres datasource template), testcontainers (so we can spin up a real Postgres in functional tests), and database-migration (Liquibase, so the production image can run schema changes on first start).

Open start.grails.org, pick the web profile, name the application docker, set the package to example, choose JDK 21, tick the postgres, testcontainers, and database-migration features, and download the generated zip. Unzip it and cd into the docker directory.

The forge unpacks into a docker/ directory containing a vanilla Grails 8 layout plus the three feature-driven additions:

Two paths produce a runnable container image from the same bootJar:

For a typical Grails 8 web app the buildpack path wins on every dimension that matters: smaller images (the buildpack’s slim JRE base is ~150 MB), better layering (a code-only change touches only the top layer), and a free non-root user. The Dockerfile path is justified when you have a regulated build that must consume an internal mirror, an air-gapped CI, or a non-buildpack-compatible base image.

This guide leads with bootBuildImage and treats the Dockerfile as an alternative.

Files touched in this chapter:

The Spring Boot Gradle plugin (already on the classpath via the Grails web plugin) registers a bootBuildImage task out of the box. The default image name is docker.io/library/<rootProject.name>:<version>, which is rarely what you want. Override it - and pin the JVM version - with a small block at the bottom of build.gradle:

Three pieces are doing the work:

The Spring Boot Gradle plugin pinned in grails-core 8.0.x is spring-boot-gradle-plugin:4.0.5 (see git show 8.0.x:dependencies.gradle for the exact coordinate); bootBuildImage is part of that plugin and is enabled automatically by the org.apache.grails.gradle.web plugin the web profile applies.

Files touched in this chapter:

Build and run the image:

The first build downloads the Paketo builder image (~600 MB) and the buildpack base layers (~150 MB JRE, ~60 MB OS) into your local Docker daemon. Subsequent builds reuse them; the per-build delta after that is just your changed classes and resources, typically under 5 MB.

When the container is up, hit it from another terminal:

The first request renders the Grails welcome page. The second returns {"status":"UP"} from the Spring Boot Actuator readiness probe we will configure in a later chapter.

Files touched in this chapter:

For teams that need explicit control over every layer, the equivalent multi-stage Dockerfile lives at the project root:

A few patterns are worth pointing at:

Files touched in this chapter:

A production image cannot ship with a hard-coded jdbc:postgresql://localhost:5432/…​ URL; the same image has to run on a developer laptop, in CI, in staging, and in production with different connection strings, credentials, and even different database servers.

Grails uses the standard Spring Boot environment-variable → property mapping. Replace the literal values in grails-app/conf/application.yml with ${SPRING_DATASOURCE_URL:fallback} placeholders:

Three things to notice:

The Compose file we will write later passes these three variables to the container. Kubernetes deployments would pass the same variables via a Secret and envFrom: { secretRef: …​ }.

Files touched in this chapter:

Two JVM flags need to be set for any JVM workload running inside a container:

You set them once in build.gradle:

The BPE_APPEND variant adds to whatever the buildpack-supplied JAVA_TOOL_OPTIONS already contains. The buildpack ships its own memory calculator output (heap, direct memory, metaspace, reserved code cache, thread stacks); appending preserves all of that and just bolts our two flags on the end.

If you switch to the hand-rolled Dockerfile you set the same two flags via ENV JAVA_TOOL_OPTIONS=…​ instead.

Files touched in this chapter:

Spring Boot Actuator (already on the classpath in the starter) exposes liveness and readiness probes at /actuator/health/liveness and /actuator/health/readiness. Enable them with a small block in application.yml:

The endpoints.web.exposure.include line restricts the public surface to just health and info; the operator-grade endpoints (metrics, env, threaddump, loggers) stay closed. endpoint.health.show-details: when-authorized means a curl against /actuator/health returns {"status":"UP"} to the world but the full per-component breakdown only to authenticated callers.

The health.livenessstate and health.readinessstate flags expose the two probes Kubernetes-style platforms expect:

For Docker Compose, the HEALTHCHECK lives on the service definition (next chapter). For Kubernetes, you would use httpGet: { path: /actuator/health/readiness, port: 8080 } instead.

Files touched in this chapter:

A compose.yml at the project root orchestrates the application image plus a real PostgreSQL service:

The shape is two services and one named volume:

Bring it all up with:

The first run pulls the Postgres image, creates the volume, starts Postgres, waits for healthy, then starts the app. Subsequent runs skip the pull.

Files touched in this chapter:

The Compose file’s app service receives three datasource variables:

Two things to highlight:

The application.yml we wrote in the env-profiles chapter resolves these three variables transparently. Spring Boot’s relaxed binding maps SPRING_DATASOURCE_URL to the property spring.datasource.url, which Grails forwards into its own dataSource.url slot. No glue code in the app itself.

Files touched in this chapter:

GitHub Container Registry (GHCR) is the easiest place to host an image for a project that already lives on GitHub: it inherits the repository’s visibility and access policies, supports anonymous pulls for public repos, and is free for public images.

Push the locally built image:

$GITHUB_TOKEN is a personal access token with the write:packages scope. From a GitHub Actions workflow it is the auto-provisioned ${{ secrets.GITHUB_TOKEN }}; from a developer laptop it is a token you mint at github.com/settings/tokens.

The first time an image is pushed under a given repo path, GHCR creates the package and links it to the same GitHub repo. Make it public via the GHCR UI (Package settings → Change visibility → Public) so anonymous pulls work without authentication.

Files touched in this chapter:

Containers should not run as root, full stop. A process running as root inside a container is root on the host kernel for the duration of any successful container break-out; even when the container runtime drops most capabilities, defence in depth says don’t start with the maximum privilege.

Both image paths in this guide give you a non-root runtime user for free:

In Kubernetes, you reinforce this at the pod level with a securityContext:

readOnlyRootFilesystem: true is the strictest setting. The Paketo image already supports it; the hand-rolled Dockerfile may need a tmpfs volume mounted at /tmp for things like Tomcat’s work directory. The trade-off is yours to make.

Files touched in this chapter: