Overview

Starting with version 26.2 of the Lobster Data Platform, the Lobster Application Wrapper replaces the previous platform-specific startup mechanisms (e.g., execute.sh, manually registered Windows services, or custom init scripts) with a unified, cross-platform solution. To achieve this, you need to follow a few steps for setup.

What the wrapper does

The Lobster Application Wrapper is a Java-based application that registers and manages your Lobster applications as system services – on Windows via the Service Control Manager, and on Linux via systemd. It can start and monitor one or more Java applications in parallel and coordinate the restart of your entire cluster, including all Lobster Data Platform instances (node controllers and worker nodes) as well as DMZ servers (primary and secondary).

Why a wrapper?

Previously, the way the Lobster Data Platform was started and stopped depended heavily on the operating system and custom configurations. These inconsistent operational procedures increased reliance on Lobster Support, particularly when restarting in cluster setups.

The wrapper solves these problems:

• Consistent commands: The same commands on Windows and Linux. No platform-specific knowledge is required.

• Self-service operation: You can start, stop, and restart your environment whenever you need to. No support ticket required, no waiting time.

• Cluster-wide restart: The wrapper coordinates the restart of all nodes (node controllers, and worker nodes) and DMZ servers (primary and secondary).

• Central configuration: You manage JVM parameters and memory settings in a single file (platform.json).

• Multi-application management: Multiple Java applications can be managed using the same wrapper.

What's changing

Architecture

The wrapper consists of the following components:

Log output

The wrapper writes its log output consistently to logs/wrapper.log—both in service mode and in console mode (--run). This applies equally to Windows and Linux. The previous console.txt file is no longer generated.

System requirements

• JDK 11 or later is installed and accessible via java on the command line.

• Lobster Data Platform ≥ 26.2 is installed.

• Administrator rights (Windows) or root privileges (Linux).

• Windows: Service Control Manager.

• Linux: systemd.

Windows wrapper: Java version compatibility

On Windows, wrapper compatibility depends on the installed wrapper generation and the Java version in use. Check your scenario in the table below.

Further information:

• Initial setup → Set up an application wrapper

• Migration → How-to: Migrate from an existing installation

• Commands and configuration → Reference

Set up an application wrapper

This guide walks you through the initial setup of the Lobster Application Wrapper step by step. When you are done, your Lobster Data Platform will run as a system service that starts automatically at system boot.

1. Verify installation files

Open a command line and navigate to the installation directory of your Lobster Data Platform. Check whether the wrapper files are present:

# Linux
ls -la ./bin/application-wrapper.jar ./bin/platform.json ./bin/wrapper.json ./bin/updater.json

# Windows
dir .\bin\application-wrapper.jar .\bin\platform.json .\bin\wrapper.json .\bin\updater.json

You should see all four files: application-wrapper.jar, platform.json, wrapper.json, and updater.json. If not, your installation may not have been updated to version 26.2 or later.

2. Check memory settings

Open the file ./bin/platform.json in a text editor and check the heap memory settings:

"-Xms4096M",
"-Xmx4096M"

Adjust the values to match the available resources on your server. Set -Xms and -Xmx to the same value to avoid dynamic memory adjustments at runtime. Typical values range from 2048M to 8192M.

3. Disable existing startup mechanisms

If your Lobster Data Platform has previously been started using other means (e.g., init scripts, manually registered services, cron jobs), disable them before installing the wrapper to avoid conflicts.

IMPORTANT

If you do not disable existing startup mechanisms, the platform will still start. The wrapper's restart functionality (--restart-service, --stop-service) will not work, however. The wrapper can only fully control the application if it is the sole control mechanism.

4. Install the service

java -jar ./bin/application-wrapper.jar --install-service

The wrapper registers the service and activates autostart on both Windows and Linux.

5. Start the service

java -jar ./bin/application-wrapper.jar --start-service

6. Check status

java -jar ./bin/application-wrapper.jar --service-status

You should see output confirming that the service is running.

7. Functional test

Log in to the Lobster Data Platform and verify that the application is working as expected. Also check the file ./logs/wrapper.log for errors.

How-to: Manage the wrapper

Migrate from an existing installation

This guide describes migrating to the wrapper when your Lobster Data Platform was previously operated using custom startup scripts or manually registered services.

Prerequisites

• Lobster Data Platform ≥ 26.2 is installed.

• You know your current JVM parameters (e.g., from execute.sh or execute.bat).

Steps

1. Back up current JVM parameters.

   Note all custom Java parameters from your existing execute.sh or execute.bat.

2. Transfer parameters to platform.json.

   Open ./bin/platform.json and add your parameters as additional entries in the jvmArgs array:

   "jvmArgs": [
       ... (keep existing entries) ...
       "-Dmy.custom.parameter=value",
       "-Danother.parameter=true"
   ]

3. Disable existing startup mechanisms.

   Disable or remove all existing services, init scripts, and other startup mechanisms.

   IMPORTANT

   This step is critical for the wrapper to function properly. If you do not disable existing startup mechanisms, the platform will still start. The wrapper's restart functionality (--restart-service, --stop-service) will not work, however. The wrapper can only fully control the application if it is the sole control mechanism.

4. Install and start the service.

   java -jar ./bin/application-wrapper.jar --install-service
   java -jar ./bin/application-wrapper.jar --start-service

5. Run a functional test.

   Check the application and the file ./logs/wrapper.log for errors.

Restart the service

java -jar ./bin/application-wrapper.jar --restart-service

Alternatively, you can stop the service and start it again separately:

java -jar ./bin/application-wrapper.jar --stop-service
java -jar ./bin/application-wrapper.jar --start-service

Disable or enable autostart (Linux only)

By default, the service starts automatically when the system boots. To change this behavior:

# Disable autostart
java -jar ./bin/application-wrapper.jar --disable-service

# Re-enable autostart
java -jar ./bin/application-wrapper.jar --enable-service

Run in console mode

For testing or troubleshooting, you can start the application directly in the console without registering it as a service:

java -jar ./bin/application-wrapper.jar --run

Log output is written to logs/wrapper.log—just as in service mode. Press Ctrl+C to terminate the process.

Change memory settings

1. Stop the service:

   java -jar ./bin/application-wrapper.jar --stop-service

2. Open ./bin/platform.json and adjust the values for -Xms and -Xmx:

   "-Xms8192M",
   "-Xmx8192M"

3. Start the service:

   java -jar ./bin/application-wrapper.jar --start-service

Add custom JVM parameters

If you need additional system properties or JVM options, add them as further entries in the jvmArgs array in platform.json:

"jvmArgs": [
    "-Xms4096M",
    "-Xmx4096M",
    "-server",
    ... (existing entries) ...
    "-Dmy.custom.parameter=value",
    "-Danother.parameter=true"
]

Restart the service afterwards for the changes to take effect.

Customize shutdown timeout

When stopping or restarting, the wrapper allows the application a configurable amount of time to shut down gracefully. The default value is 120 seconds. If the application exceeds the timeout, the wrapper forces the process to terminate. On platforms with many concurrent or long-running processes, increasing this timeout may be advisable to ensure that open transactions can be completed properly.

1. Stop the service:

   java -jar ./bin/application-wrapper.jar --stop-service

2. Open ./bin/wrapper.json and adjust the value of process.shutdown.timeout (specified in seconds).

3. Start the service:

   java -jar ./bin/application-wrapper.jar --start-service

Fully uninstall the service

# Stop the service
java -jar ./bin/application-wrapper.jar --stop-service

# Uninstall the service
java -jar ./bin/application-wrapper.jar --uninstall-service

Reference: Commands and configuration

All commands are executed via the wrapper JAR file:

java -jar ./bin/application-wrapper.jar <command>

Configuration file: platform.json

Path: ./bin/platform.json

The file platform.json is the central configuration file for your application service. It contains JVM parameters, memory settings, and the classpath. Always create a backup before making any changes.

Parameters

Memory settings

Variables

Configuration file: wrapper.json

Path: ./bin/wrapper.json

The file wrapper.json contains the wrapper's internal service configuration. Only the parameters listed below are intended for customization. All other entries—especially references to loaded applications and their configuration files such as updater.json and platform.json—are internal configuration and must not be modified.

Parameters

Recommendation

On platforms with many concurrent or long-running processes, a higher value for process.shutdown.timeout may be advisable to ensure that open transactions can be completed properly before the process is forcefully terminated.

File overview