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 do 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 required.

• Self-service operation – You can start, stop, and restart your environment whenever you need to – without submitting a support ticket and without any waiting time.

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

• Central configuration – JVM parameters and memory settings are managed in a single file (platform.json).

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

What's changed

Architecture

The wrapper consists of the following components:

Log output

The wrapper writes its log output to logs/wrapper.log – both when running as a system service 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 can be accessed via java on the command line.

• Lobster Data Platform version 26.2 or later 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: Migration from an existing installation

• Commands and configuration → Reference

Set up an application wrapper

These instructions will guide you step by step through the initial setup of the Lobster Application Wrapper. By the end, your Lobster Data Platform will be running as a system service that starts automatically when the system boots.

1. Check the installation files

Open a command prompt 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
# Windows
dir .\bin\application-wrapper.jar .\bin\platform.json

You should see all four files: application-wrapper.jar, platform.json, wrapper.json und 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 your server's available resources. 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 existing startup mechanisms are not disabled, the platform will still start, but the wrapper's restart functionality (--restart-service, --stop-service) will not work. 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 service is registered and automatically configured to start at system boot on both Windows and Linux.

5. Start the service

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

6. Check the status

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

You should see a message 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 ./logs/wrapper.log for errors.

How to manage the wrapper

Migration from an existing installation

These instructions describe how to migrate to the wrapper if your Lobster Data Platform has previously been operated using custom startup scripts or manually registered services.

Requirements

• Lobster Data Platform ≥ 26.2 is installed.

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

Steps

1. Save your current JVM parameters.

   Make a note of 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 existing startup mechanisms are not disabled, the platform will still start, but the wrapper's restart functionality (--restart-service, --stop-service) will not work. 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. Perform a functional test.

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

Restart the service

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

Alternatively, you can stop the service and restart it 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

Launch the application 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

The log output is written to logs/wrapper.log – the same location used in service mode. Terminate the process by pressing Ctrl+C.

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 additional entries in the jvmArgs array of the platform.json file:

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

To apply the changes, restart the service.

Customize shutdown timeout

When stopping or restarting, the wrapper allows the application a configurable amount of time to shut down gracefully. The shipped wrapper.json sets this value to 120 seconds (if no entry is present, an internal default of 60 seconds applies). If this time limit is exceeded, 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

Uninstall the service completely

# 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 platform.json file is the central configuration file for your application service. It contains JVM parameters, memory settings, and the classpath. Always create a backup copy before making any changes.

Parameters

Memory settings

Variables

Configuration file: wrapper.json

Path: ./bin/wrapper.json

The wrapper.json file contains the wrapper's internal service configuration. Only the parameters listed below are intended for customization – all other entries (in particular the 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

For 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