Skip to content

Develop and run your own Gradle project

This procedure builds a standalone application using J7M Maven artifacts. It does not use Gradle project(...) dependencies, a composite build or classes from a J7M source checkout. The application runs through the same platform host that an operator installs from a release archive.

You need a JDK 25, an Internet connection for the first build and a published J7M version. The starter includes the Gradle wrapper. Operators who only need to run the finished application should follow platform installation.

Obtain the complete starter

Choose a version from GitHub Releases whose Maven Central deployment is PUBLISHED and whose release includes j7m-starter-VERSION.zip. The commands use 0.9.9; substitute an available published version. A GitHub release can exist while Central is still waiting for manual publication.

J7M_VERSION=0.9.9
J7M_RELEASE="https://github.com/Egothor/J7M/releases/download/release%40${J7M_VERSION}"
curl --fail --location --remote-name "$J7M_RELEASE/j7m-starter-${J7M_VERSION}.zip"
curl --fail --location --remote-name "$J7M_RELEASE/SHA256SUMS"
grep "  j7m-starter-${J7M_VERSION}.zip$" SHA256SUMS | sha256sum --check -
unzip "j7m-starter-${J7M_VERSION}.zip"
cd "j7m-starter-${J7M_VERSION}"
java -version
./gradlew --version

The commands below use a POSIX/Linux environment. The archive also includes gradlew.bat, but the example's automatic signing-key creation requires POSIX file permissions. On another filesystem, provide an externally protected Ed25519 key pair as described below rather than assuming the key-generation task configures Windows ACLs. The source form of the same starter is in examples/standalone-application in the J7M repository. It remains an independent Gradle project.

Set up Gradle dependencies

settings.gradle gives the application its own build identity:

rootProject.name = 'hello'

Keep the J7M release in gradle.properties:

j7mVersion=0.9.9

The build must resolve both the packaging plugin and application dependencies from Maven Central. The plugin implementation is published under org.egothor:j7m-gradle-plugin; the plugin ID remains org.j7m.application. Load that implementation explicitly instead of assuming an org.j7m plugin marker exists on the Gradle Plugin Portal:

buildscript {
    repositories {
        if (project.hasProperty('j7mRepository')) {
            exclusiveContent {
                forRepository { maven { url = uri(project.property('j7mRepository')) } }
                filter { includeGroup 'org.egothor' }
            }
        }
        mavenCentral()
    }
    dependencies {
        classpath "org.egothor:j7m-gradle-plugin:${providers.gradleProperty('j7mVersion').get()}"
    }
}

plugins { id 'java' }
apply plugin: 'org.j7m.application'

def j7mVersion = providers.gradleProperty('j7mVersion').get()

java {
    toolchain { languageVersion = JavaLanguageVersion.of(25) }
}

repositories {
    if (project.hasProperty('j7mRepository')) {
        exclusiveContent {
            forRepository { maven { url = uri(project.property('j7mRepository')) } }
            filter { includeGroup 'org.egothor' }
        }
    }
    mavenCentral()
}
configurations { j7mPlatform }

dependencies {
    compileOnly "org.egothor:j7m-api:$j7mVersion"
    annotationProcessor "org.egothor:j7m-annotation-processor:$j7mVersion"
    j7mPlatform "org.egothor:j7m-deployer-cli:$j7mVersion"
}

Maven Central is the normal source. j7mRepository is an optional Maven repository URL for testing an unpublished release candidate; it must contain the complete matching J7M publication, including its processor, plugin and host. Omit that property for a published release.

Dependency/configuration Purpose
compileOnly J7M API Compiles the application against the API provided by the platform. It is not copied into the application's bundle.
annotationProcessor Runs the real processor at compilation and generates component/schema metadata. It is not a runtime dependency.
Plugin buildscript classpath Provides the packaging, signing and verification tasks.
j7mPlatform Resolves the executable platform host and its runtime dependencies for the developer's run task.

Add another org.egothor:j7m-* compile dependency when application source uses that module's API. Add third-party application libraries to the bundle's declared libraries. Do not copy platform implementation JARs into an application bundle simply to satisfy compilation; the installed platform supplies them.

Append the signing, packaging and run configuration to the same build.gradle:

tasks.register('generateSigningKey') {
    def privateFile = layout.buildDirectory.file('signing/private.der')
    def publicFile = layout.buildDirectory.file('signing/public.der')
    outputs.files(privateFile, publicFile)
    doLast {
        if (privateFile.get().asFile.exists() || publicFile.get().asFile.exists()) {
            if (!privateFile.get().asFile.isFile() || !publicFile.get().asFile.isFile()) {
                throw new GradleException('Incomplete existing signing key pair')
            }
        } else {
            def pair = java.security.KeyPairGenerator.getInstance('Ed25519').generateKeyPair()
            def keyDirectory = privateFile.get().asFile.parentFile.toPath()
            java.nio.file.Files.createDirectories(keyDirectory)
            if (java.nio.file.Files.getFileStore(keyDirectory).supportsFileAttributeView('posix')) {
                java.nio.file.Files.setPosixFilePermissions(keyDirectory,
                    java.nio.file.attribute.PosixFilePermissions.fromString('rwx------'))
                def permissions = java.nio.file.attribute.PosixFilePermissions.asFileAttribute(
                    java.nio.file.attribute.PosixFilePermissions.fromString('rw-------'))
                java.nio.file.Files.createFile(privateFile.get().asFile.toPath(), permissions)
            } else {
                throw new GradleException('Use externally protected Ed25519 key files on non-POSIX systems')
            }
            java.nio.file.Files.write(privateFile.get().asFile.toPath(), pair.private.encoded)
            publicFile.get().asFile.bytes = pair.public.encoded
        }
    }
}

j7m {
    manifest.set(layout.projectDirectory.file('META-INF/j7m-application.json'))
    bundleFile.set(layout.buildDirectory.file('distributions/hello.j7m'))
    signingKeyId.set('publisher')
    signingPrivateKey.set(layout.buildDirectory.file('signing/private.der'))
    signingPublicKey.set(layout.buildDirectory.file('signing/public.der'))
    verificationProfile.set('strict-production')
}

tasks.named('j7mSign') { dependsOn 'generateSigningKey' }

tasks.register('preparePlatformConfiguration') {
    dependsOn 'j7mVerify'
    inputs.file(layout.projectDirectory.file('conf/developer.properties'))
    inputs.file(j7m.bundleFile)
    outputs.file(layout.buildDirectory.file('platform.properties'))
    doLast {
        def properties = new Properties()
        file('conf/developer.properties').withInputStream { properties.load(it) }
        def digest = java.security.MessageDigest.getInstance('SHA-256')
        j7m.bundleFile.get().asFile.withInputStream { input ->
            byte[] block = new byte[65536]
            int count
            while ((count = input.read(block)) != -1) digest.update(block, 0, count)
        }
        // Keep mutable development builds separate from immutable operator releases.
        properties.setProperty('repository.path', 'platform-repository/' + digest.digest().encodeHex().toString())
        layout.buildDirectory.file('platform.properties').get().asFile.withOutputStream {
            properties.store(it, 'Paths relative to this generated configuration')
        }
    }
}

tasks.register('run', JavaExec) {
    dependsOn 'preparePlatformConfiguration'
    classpath = configurations.j7mPlatform
    mainClass = 'org.j7m.middleware.deployer.cli.J7mPlatform'
    args '--config', layout.buildDirectory.file('platform.properties').get().asFile.absolutePath
    jvmArgs '--enable-native-access=ALL-UNNAMED', '--sun-misc-unsafe-memory-access=allow'
}

Together, the two build fragments are a complete build.gradle for the source, manifest and conf/developer.properties supplied in the starter. Keep build/ and .gradle/ excluded from version control; the generated private key must not be committed.

Build generated metadata and a signed bundle

The sample application has coordinate example:hello:1.0.0. Its manifest and annotated component are included in the starter. The manifest selects the managed annotation profile so the platform loads the generated metadata.

./gradlew clean build
./gradlew generateSigningKey j7mVerify

generateSigningKey creates an Ed25519 key pair in build/signing/:

File Handling
private.der PKCS#8 private key used by the developer's signing task; keep private.
public.der X.509 public key supplied to the operator through a trusted channel.

The build configures signingPrivateKey, signingPublicKey and signingKeyId = 'publisher' on the J7M plugin. It signs build/distributions/hello.j7m and verifies it with the matching public key under the strict-production signature policy. A signature policy checks artifact trust; its name does not certify your application's operational security.

For later builds of the same publisher, protect and reuse your signing key outside disposable build outputs. Do not distribute the private key or make an operator trust a key solely because it arrived inside an application bundle.

Automatic key creation makes build/signing/ owner-only and creates the private file with owner read/write permission before writing any private-key bytes. On a non-POSIX filesystem, first install your externally protected PKCS#8 private.der and matching X.509 public.der at the configured paths, or change the two plugin file properties to your protected locations. The example task keeps an existing complete key pair; it does not manage operating-system ACLs or a production signing service.

Run during development

./gradlew run

The starter's run task verifies the bundle, writes its platform configuration and launches org.j7m.middleware.deployer.cli.J7mPlatform from the separate j7mPlatform configuration. Application classes are loaded from the verified bundle, not from the host's classpath.

The supplied developer configuration is conf/developer.properties. It is copied to build/platform.properties; paths in the generated file resolve relative to build/, so distributions/hello.j7m and signing/public.der refer to the generated bundle and public key. The default greeting is Hello from Gradle.

The sample writes HELLO_STARTED Hello from Gradle, and the host reports J7M_PLATFORM_RUNNING example:hello:1.0.0 and J7M_PLATFORM_PID followed by the host process ID. It remains running. For a graceful development shutdown, open a second terminal and signal that printed host PID:

kill -TERM HOST_PID

Replace HOST_PID with the numeric value printed by this host. Shutdown writes HELLO_STOPPED and J7M_PLATFORM_STOPPED. Gradle may report the signalled Java process's nonzero exit status; that is distinct from an application shutdown failure. Cancelling Gradle itself with Ctrl+C can forcibly terminate its JavaExec child, so it is not the shutdown proof used by this procedure.

Edit the sample developer configuration to change the greeting and rerun the task. The starter gives each signed bundle digest its own development repository under build/platform-repository/, so repeated runs and edit/rebuild cycles do not collide with a previous bundle at the sample's coordinate. These stores are disposable development state; the task does not delete or overwrite an existing immutable repository entry.

When delivering changed bundle bytes to an operator's persistent repository, publish a new application coordinate version. The installed platform keeps its fixed repository path and rejects different bytes for an existing coordinate.

Do not substitute j7mRunLocal for this task. That legacy plugin task reports unavailable lifecycle execution; the starter's run task launches the actual host.

Deliver the application

Give the operator:

  • build/distributions/hello.j7m;
  • build/signing/public.der, with key ID publisher;
  • the required J7M version and the application's configuration requirements.

The operator obtains the matching platform archive, installs the bundle and public key, then starts bin/j7m-platform. Gradle and the annotation processor remain on the developer side. The sample platform configuration does not provision a native queue, job or saga backend; those features require the explicit host and resource configuration described by the corresponding application.