Skip to content

Install the platform and run an application

Download the platform and the supplied Hello application to run the first example entirely from release assets. You can then install a signed .j7m bundle from your own application publisher. The platform archive contains the executable host, J7M libraries and a configuration file. You need Java 25; you do not need Gradle, Maven or a J7M source checkout on the application host.

The Hello application archive contains its signed bundle, demo public key and offline instructions. It contains no private signing key. The developer procedure shows how to produce and deliver your own application instead.

Download and unpack a release

Choose a published J7M version from GitHub Releases. The commands use 0.9.9; replace it with a release that lists the platform archives, j7m-hello-VERSION.zip and SHA256SUMS. These URLs identify release assets produced by the release workflow; an unreleased version is not downloadable merely because it appears in this manual.

For Linux or another Unix-like host:

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-platform-${J7M_VERSION}.tar.gz"
curl --fail --location --remote-name "$J7M_RELEASE/j7m-hello-${J7M_VERSION}.zip"
curl --fail --location --remote-name "$J7M_RELEASE/SHA256SUMS"
grep "  j7m-platform-${J7M_VERSION}.tar.gz$" SHA256SUMS | sha256sum --check -
grep "  j7m-hello-${J7M_VERSION}.zip$" SHA256SUMS | sha256sum --check -
tar -xzf "j7m-platform-${J7M_VERSION}.tar.gz"
unzip "j7m-hello-${J7M_VERSION}.zip"
cd "j7m-platform-${J7M_VERSION}"
java -version

The ZIP asset is named j7m-platform-VERSION.zip. On Windows, extract it and use bin\j7m-platform.bat with the same --config argument. Set JAVA_HOME to the Java 25 installation if it is not already the default Java.

The installed layout separates executable code from application and runtime state:

j7m-platform-VERSION/
  bin/                 platform launchers
  lib/                 platform and dependency JARs
  conf/                platform.properties
  applications/        signed application bundles supplied by publishers
  trust/               trusted public signing keys
  var/repository/      local application repository created by the host

Install the supplied Hello application

The example archive extracts into j7m-hello-VERSION/ beside the platform. From the platform installation directory:

mkdir -p applications trust var/repository
cp "../j7m-hello-${J7M_VERSION}/hello.j7m" applications/hello.j7m
cp "../j7m-hello-${J7M_VERSION}/publisher.der" trust/publisher.der

The demo key authorizes this released Hello application under signing key ID publisher. Use it only for this example. Your own publisher's applications need the publisher key you have chosen to trust; the demo key is not a general production signing authority.

Proceed to the configuration and startup below. No build step is needed.

Install your own publisher's application instead

Receive these two files from the application publisher:

File Meaning
hello.j7m Immutable signed bundle for example:hello:1.0.0
public.der Publisher's Ed25519 public key in X.509 DER format

Confirm the public key with the publisher through your normal trusted delivery process. A key included beside a downloaded bundle does not establish who owns it. The operator needs the public key only; keep the publisher's private.der off the application host.

From the platform installation directory, copy the received files:

mkdir -p applications trust var/repository
cp /path/to/received/hello.j7m applications/hello.j7m
cp /path/to/received/public.der trust/publisher.der

Use the publisher's actual bundle name, signing key ID and configuration when editing conf/platform.properties. These commands are an alternative to installing the supplied Hello example, not an additional requirement for it.

Keep bin/, lib/, conf/, applications/ and trust/ under the operator's control. The service account must be able to read them and write its own var/repository/. Preserve that repository across an ordinary restart.

Configure the host

Edit conf/platform.properties:

runtime.id=j7m-platform
application.bundle=../applications/hello.j7m
repository.path=../var/repository
trust.key-id=publisher
trust.public-key=../trust/publisher.der
application.environment=production
application.config.j7m.annotations.profile=managed-v1
application.config.greeting.message=Hello from installed J7M

Paths are relative to the configuration file, not to the shell's current directory. The signing key ID must match the ID used when the publisher signed the bundle. application.config.* values are passed to the application without the prefix. The managed annotation profile selects generated component hosting; it does not provision durable resource groups or grant additional permissions.

Start and stop

Run the actual platform host in the foreground:

bin/j7m-platform --config conf/platform.properties

The host verifies the application against the configured public key, imports it into the local repository and activates it through ApplicationManager. The sample application writes:

HELLO_STARTED Hello from installed J7M

The host also writes J7M_PLATFORM_RUNNING example:hello:1.0.0 after activation has entered RUNNING.

The process remains running. Stop it with Ctrl+C, or send SIGTERM from your process supervisor. The host deactivates the application and closes the runtime; the sample writes HELLO_STOPPED. For a service installation, configure the supervisor's working directory, Java 25 environment, service account, standard-output/error logging and sufficient graceful-stop time. Do not use kill -9 for an ordinary shutdown.

The supplied host uses loopback gRPC/RMI defaults and disables the nugget administration endpoint. Its application.environment=production setting is application metadata; it does not enable TLS or expose a remotely managed production service. The properties shown here configure bundle trust, application values and local storage. An application needing authenticated remote endpoints or native resource factories requires an explicitly assembled host with those capabilities; copying additional property names does not install them.

The separate j7m-deployer-cli tool still provides packaging and repository commands. Its legacy app start command and the Gradle plugin's j7mRunLocal task do not replace this executable host.

Diagnose startup failures

Symptom Check
Java class-version error The launcher is using Java 25, including when started by a supervisor.
Configuration or file error The configuration file exists; bundle/key paths resolve relative to it and are readable by the service account.
Signature rejection Bundle bytes are unchanged, key ID matches, and the configured public key is the publisher key you trust.
Coordinate conflict A different bundle cannot replace an already imported version; obtain a new application version from its publisher.
Activation failure Inspect the application's startup error and provide the resources, configuration and host capabilities declared by that application.

Use upgrade and rollback for the application lifecycle contract and network configuration when moving beyond a single-host installation. The supplied example proves this install/start/stop path; it does not configure a native consensus cluster or a cross-host TLS topology.