Running a Liberty server from a JAR file

You can start a Liberty server from a Java archive (JAR) file. This method provides a compact, portable way of starting a Liberty server. You create the JAR file by using the Liberty server command and then run as an executable JAR file by using the java -jar command.

Open Liberty The latest documentation about runnable JAR files for Liberty is available on the Open Liberty website.

Create the runnable JAR file

You can specify minify to get the smallest archive possible. You must specify a JAR type archive to get a runnable JAR file. The default archive type is .zip on all platforms except z/OS, where the only supported type is pax. For example:

server package <server name> --include=[minify,]runnable --archive=<jar file name>.jar

Run the JAR file

Run the JAR file by using the standard java command with the -jar option, for example: 
java -jar <jar file name>.jar

Operation

When the JAR file runs, it gets extracted to a temporary location and then the server runs in the foreground, started by the Liberty server run command. All output is written to stdout or stderr. By default, files are extracted to temporary locations:
  • For Windows: %HOMEPATH%/wlpExtract/<jar file name>_nnnnnnnnnnnnnnnnnnn
  • For all other platforms: $HOME/wlpExtract/<jar file name>_nnnnnnnnnnnnnnnnnnn

You can control the output location by using the WLP_JAR_EXTRACT_ROOT or WLP_JAR_EXTRACT_DIR environment variable.

Stopping the server

To stop the Liberty server press Ctrl-C. When the Liberty server stops, the extraction directory is automatically deleted. If you stop the active shell in any other way, the extraction directory is not cleaned up automatically, you must clean it up manually.

Run in debug mode

You can run the Liberty server in debug mode if you set the environment variable WLP_JAR_DEBUG before you start the server.

Controlling output

By default, server output is written to the extraction directory, which is deleted when the server stops. If you want to save the output, specify a durable output location by using the WLP_OUTPUT_DIR environment variable before you start the server.

Two-phase commit transactions

By default, two-phase commit commit transactions are disabled because the transaction logs are in the expansion directory and are deleted when the Liberty server is stopped. Therefore, transaction recovery is not possible.

To enable two-phase commit, configure the transaction log to be in a durable location in the file system or an RDBMS and set the WLP_JAR_ENABLE_2PC environment variable.

To configure the transaction log, use either the transactionLogDirectory or dataSourceRef attribute on the transaction element in your server.xml configuration.

Running under CYGWIN

Running a Liberty server JAR file in a CYGWIN shell has two requirements:

  1. Specify the WLP_JAR_CYGWIN environment variable.

    This variable causes the Liberty server JAR runner to do UNIX-style file and process handling when it is running in the CYGWIN environment.

  2. Run under the bash shell, not mintty.

    Automatic extraction file deletion occurs only when you run under the bash shell. You can run under mintty, but you must delete the extraction files manually. Mintty does not forward the necessary signal that is required to trigger Java shutdown hooks.

Environment variable reference

Table 1. The environment variable names and their definitions
Environment variable name Description
WLP_JAR_EXTRACT_ROOT Extracts JAR file to directory ${WLP_JAR_EXTRACT_ROOT}/<jar file name>_nnnnnnnnnnnnnnnnnnn
WLP_JAR_EXTRACT_DIR Extracts JAR file to directory ${WLP_JAR_EXTRACT_DIR}.
WLP_OUTPUT_DIR Writes Liberty server output files to directory ${WLP_OUTPUT_DIR}.
WLP_JAR_DEBUG Runs Liberty server by using server debug <server name> instead of server run <server name>.
WLP_JAR_ENABLE_2PC Set to value true to enable 2PC when the runnable JAR file runs.
WLP_JAR_CYGWIN Set to value true if you are running the JAR file under CYGWIN.