Docs menu

Customizing the build

How to shape a Java build on Primcloud: custom Maven goals and Gradle tasks, native dependencies, trusting a private CA, and Debian packages.

On this page

Most Java apps deploy on Primcloud with no custom build steps: install a JDK, run Maven or Gradle, and that's it. When you need more, the extension points live in the build tool itself (Maven lifecycle phases, Gradle tasks), a few environment variables, or a project.toml for OS-level packages.

Build hooks#

Pre- and post-build work belongs in the build tool's own extension points, so local and Primcloud builds stay identical.

Maven: bind to a lifecycle phase. Attach an execution to the phase you want to hook. For example, run a script during prepare-package:

pom.xml
<plugin>
  <groupId>org.codehaus.mojo</groupId>
  <artifactId>exec-maven-plugin</artifactId>
  <executions>
    <execution>
      <id>pre-package-script</id>
      <phase>prepare-package</phase>
      <goals>
        <goal>exec</goal>
      </goals>
      <configuration>
        <executable>./scripts/pre-package.sh</executable>
      </configuration>
    </execution>
  </executions>
</plugin>

Gradle: declare a task and wire it into the graph. Chain from the stage task so it runs in the standard build:

build.gradle
task stampBuildInfo(type: Exec) {
  commandLine './scripts/stamp-build-info.sh'
}

stage.dependsOn stampBuildInfo

Environment variables set on the environment are available to <exec> and Exec tasks at build time.

Custom install steps#

To change the build command itself (Maven goals, Gradle tasks, the JVM heap for the build), use these environment variables:

Maven:

  • MAVEN_CUSTOM_GOALS: replace the default clean install goals. For example, package -pl web-module -am to package a single module.
  • MAVEN_CUSTOM_OPTS: replace the default -DskipTests options. For example, -DskipTests -P production to activate a Maven profile.
  • MAVEN_OPTS: JVM flags for Maven during the build, such as a larger -Xmx if a big multi-module build runs out of heap.

Gradle:

  • GRADLE_TASK: replace the default stage task. For example, bootJar to build a Spring Boot fat JAR directly.

Set these under Settings → Secrets. They take effect on the next build. To choose the Maven version used when no wrapper is present, set maven.version in system.properties (see Package managers).

Native dependencies#

Two shapes of "native" your Java app can rely on:

JNI libraries bundled in JARs. Libraries like JavaCV, JNA, or Netty's native transports ship platform-specific .so files inside their JARs, extract them at runtime, and load them with System.loadLibrary. No extra setup; they work as long as the JAR carries a Linux x86-64 or ARM64 variant.

OS-level shared libraries your code calls through JNI/JNA/FFM, or that a JAR-bundled native depends on: libssl, libcrypto, libjemalloc, and the like. These come from the operating system, not a JAR. Install them with a project.toml, covered below.

Trusting a private CA#

If your Java code connects over HTTPS to a host whose certificate is signed by a private CA, bundle a trust store in your repo and point the JVM at it. Build the trust store locally by importing your CA certificate, then commit it:

Terminal
keytool -importcert -alias my-private-ca -file my-ca.crt \
  -keystore truststore.jks -storepass changeit -noprompt

Point your launch command at it in the Procfile:

Procfile
web: java -Djavax.net.ssl.trustStore=truststore.jks -Djavax.net.ssl.trustStorePassword=changeit -Dserver.port=$PORT -jar target/myapp.jar

To keep every JVM on the process using it without editing the command, set the same flags in JAVA_TOOL_OPTIONS under Settings → Secrets. Public CAs are trusted out of the box, so you only need this for a private or internal CA.

Debian packages#

When your app needs system libraries or command-line tools that aren't already installed, list them in a project.toml at the root of your repo:

project.toml
[_]
schema-version = "0.2"

[com.heroku.buildpacks.deb-packages]
install = [
  "libjemalloc2",
  "libpq5",
]

Each entry is a package name from the Ubuntu 24.04 archive. Its programs and libraries are available during the build and at runtime.

Advanced options (rarely needed):

  • Skip a package's dependencies: { name = "some-package", skip_dependencies = true }
  • Force a reinstall: { name = "some-package", force = true }
  • Install from a URL: download = ["https://example.com/package-1.2.3.deb"]
  • Add a package repository: a [[com.heroku.buildpacks.deb-packages.sources]] table with uri, suites, components, arch, and signed_by (the repository's key as an ASCII-armored PGP block).

Note

The build doesn't read an Aptfile. If your repo has one, the build log warns you and nothing in it is installed. Move the packages into project.toml as shown above.