JVM startup parameters configuration

Protector4J allows configuring JVM startup parameters during packaging, as well as temporarily adding or directly modifying the generated startup script after deployment. For other advanced parameters in the GUI, see Protector4J Advanced Mode Settings.

1. Three configuration methods

It is recommended to place long-term parameters in GUI tasks or CLI commands, using APP_JAVA_OPTS for temporary overrides. After directly modifying the generation script, the changes should be recorded in the deployment configuration; they need to be reapplied during the next repackaging.

2. Configure in the GUI.

1. Select Advanced — customise the options yourself on the input page; for simple mode, click Customize… on the final page to access advanced parameters.
2. Find JVM startup options within Common options.
3. Enter one complete parameter per line, for example:

-Xms512m
-Xmx2g
-Dfile.encoding=UTF-8
-Dspring.profiles.active=prod

4. Review in the final parameter summary, then enable protection.

These parameters will be automatically written to the generated run.sh and run.bat; macOS’s run.command calls run.sh, so the same parameters are used. Tomcat parameters are also included in the startup paths of bin/catalina.sh and bin/catalina.bat. Library Encryption only generates archives and does not create startup scripts, so this configuration is not available.

3. Configure in the CLI.

Use --jvm-option once for each parameter; do not combine multiple JVM parameters into a single value.

p4j javaapp app.jar dist \
  --jvm-option -Xms512m \
  --jvm-option -Xmx2g \
  --jvm-option -Dfile.encoding=UTF-8

Spring Boot:

p4j springboot app.jar dist \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

Tomcat:

p4j tomcat app.war dist \
  --context /app \
  --jvm-option -Xms1g \
  --jvm-option -Xmx2g

Single parameters containing spaces or special characters should be quoted as a whole:

--jvm-option '-Dexample.message=hello world'

The encoder will escape the parameters separately for shell and batch scripts based on their boundaries.

4. macOS / Linux: Modify the script directly.

For regular Java and Spring Boot applications, edit run.sh in the output directory. run.command merely redirects to run.sh, so there is no need to modify it again.

Find JVM_OPTS=(...) and any subsequent JVM_OPTS+=(...) files, then add a line before checking in APP_JAVA_OPTS.

JVM_OPTS+=("-Xms512m" "-Xmx2g" "-Dfile.encoding=UTF-8")
if [ -n "${APP_JAVA_OPTS:-}" ]; then
  # ...
fi

Do not delete the --add-opens, --module-path, or --add-modules parameters already generated by Spring Boot/JavaFX.

Edit bin/catalina.sh in Tomcat, and add content after JVM_OPTS=(...) in run_java().

run_java() {
  JVM_OPTS=(...)
  JVM_OPTS+=("-Xms1g" "-Xmx2g")
  # ...
}

This modification affects both the foreground operation of run.sh and the background startup of bin/startup.sh.

5. Windows: Modify the script directly.

For regular Java and Spring Boot applications, edit run.bat to change the output directory. Locate the generated set "JVM_OPTS=..." line and append the following before the judgment in APP_JAVA_OPTS:

set "JVM_OPTS=%JVM_OPTS% -Xms512m -Xmx2g -Dfile.encoding=UTF-8"
if defined APP_JAVA_OPTS set "JVM_OPTS=%JVM_OPTS% %APP_JAVA_OPTS%"

Retain the existing content of JVM_OPTS; do not delete the internal parameters required by Spring Boot/JavaFX.

Windows Tomcat running in the foreground.

Edit bin\catalina.bat and append the following after the existing set "JVM_OPTS=...":

set "JVM_OPTS=%JVM_OPTS% -Xms1g -Xmx2g"

This will affect run.bat or bin\catalina.bat run.

Windows Tomcat starting in the background.

bin\startup.bat uses PowerShell to create a background process. The simplest way to make permanent changes is to set APP_JAVA_OPTS before calling catalina.bat:

@echo off
set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
call "%~dp0catalina.bat" start %*
exit /b %ERRORLEVEL%

To support both the frontend and backend without maintaining scripts in two places, prefer to regenerate the Tomcat package using --jvm-option via GUI or CLI.

6. Use APP_JAVA_OPTS temporarily.

macOS / Linux

APP_JAVA_OPTS="-Xms512m -Xmx2g" ./run.sh

Tomcat:

APP_JAVA_OPTS="-Xms1g -Xmx2g" ./bin/startup.sh

Windows CMD

Set this in the current CMD session (subsequent commands will inherit it; use set APP_JAVA_OPTS= to clear it):

set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
run.bat

It only takes effect in a local scope; the original environment is restored after execution.

setlocal
set "APP_JAVA_OPTS=-Xms512m -Xmx2g"
call run.bat
endlocal

Tomcat:

set "APP_JAVA_OPTS=-Xms1g -Xmx2g"
bin\startup.bat

Windows PowerShell

$env:APP_JAVA_OPTS = '-Xms512m -Xmx2g'
.\run.bat
Remove-Item Env:APP_JAVA_OPTS

7. Parameter order and notes

• Runtime parameters generated by the tool come first, followed by parameters configured via GUI/CLI, with APP_JAVA_OPTS added last.
• Values that appear after certain JVM parameters will override previous values, but not all parameters allow duplication; rely on duplicate parameters for override should be avoided.
• APP_JAVA_OPTS requires parameters separated by spaces, making it unsuitable for complex single parameters that contain spaces; for such parameters, use the GUI, --jvm-option, or edit the script array directly.
• JVM parameters must be placed before the main class or -jar; application parameters should be placed after the run.sh/run.bat commands.
• After modifying the heap size, it should be verified in conjunction with the container’s memory limits, the available memory of the operating system, and actual load.
• Repackaging will overwrite the startup script, while manual changes will not be automatically merged.