Package a Liberty server from the command line

  1. Overview
  2. Package Liberty server
  3. Package Liberty runtime


Overview

From the command line, we can create a compressed file (.zip) containing...

  • Liberty runtime environment
  • Files in the shared resources directory
  • A standalone server
  • Applications embedded in the server
  • Runtime binary files (Optional)

We can then distribute this package, using it to deploy the installation to a different location or to another machine, or embed the installation in a product distribution. We can package only a stand-alone server. The server to package cannot already be joined to a collective.

The tool used to open the file must be able to use UTF-8 encoding for entry names. The jar command in a Java SDK uses this format.

When we run the server package command with a loose application my_app.war.xml file that uses server variable substitution, those parts of the loose application having variable substitution are not packaged. The server is not started at the time of packaging and has no way to access the needed variable information. Variable substitution does not take place when we use the server package command.

Before starting stop the server.


Package the Liberty server

The default archive format is .zip on all platforms apart from z/OS where it is .pax. We can also generate a .jar.

If we do not specify a server name, defaultServer is used. If we do not specify the --archive parameter, the value of server_name is used for mypackage, and the compressed file is created in the ${server.output.dir} directory.

  • Generate a .zip archive.

      cd LIBERTY_HOME/wlp/bin
      server package server_name --archive=/path/to/mypackage.zip --include=all

    If the full path is omitted, mypackage.zip is created in ${server.output.dir}.

    Generate a .jar archive.

    The advantage of a .jar archive is that the scripts in the bin directory keep their permissions, so they are executable when the package is installed.

      server package server_name --archive=mypackage.jar --include=all

    See Java archive file extraction options.

  • Generate a .pax archive.

      server package server_name --archive=/path/to/mypackage.pax --include=all

    If the full path is omitted, mypackage.pax is created in ${server.output.dir}.

    The pax archive format saves the extended attributes required for the Liberty to work as designed in all supported scenarios. If a compressed file in ZIP format is required, specify the target archive name and include the .zip extension.

    The archive formats of .jar and .zip are not valid on z/OS.

The --include=all option packages the runtime binary files and the relevant files in the ${WLP_USER_DIR} directory; the --include=usr option packages only relevant files in the ${WLP_USER_DIR} directory, effectively excluding the runtime binary files from the compressed file.

Use the --server-root option with this command to specify the root folder which is created within the file specified by the --archive option. By default, the root folder is /wlp. For example, --server-root=MyRoot would create the root folder structure as /MyRoot inside the archive. If the --server-root command is used with the --include=usr option, the root folder would be /MyRoot/servers instead of the default value of/wlp/usr/servers.

The --include=usr option is not valid with an archive format of .jar.

If we use the --include=minify option, the server command packages only those parts of the runtime environment, and files in the ${WLP_USER_DIR} directory, required to run the server. This option significantly reduces the size of the resulting archive.

The parts of the runtime environment retained by the minify operation depend on the features configured in the server we are packaging. Only those features required to run the server are retained, and the remaining features are removed. We cannot later enable a feature that has been removed. For example, if only the servlet-3.0 feature is retained, we cannot later enable the jpa-2.0 feature.

We can repeat the minify operation to further reduce the size of the archive if the configuration is changed. There is, however, no reverse operation for the minify operation, so if we later require one or more features that have been removed, we must begin again with a complete Liberty server.

While the minify operation is running, the server is temporarily started, and we see the associated messages. For this reason, we cannot use the --include=minify option with a server that is not able to be started, but we can package it with the --include=all or --include=usr options.

We can specify the operating systems that we want the packaged server to support using the --os option with the --include=minify option. For example, to package a server with z/OS support removed:

    server package --archive="nozos.zip" --include=minify --os=-z/OS

To package a server with OS/400 support retained, but z/OS support removed:

    server package --archive="small.zip" --include=minify --os=OS/400,-z/OS

To package a server that supports only Linux:

    server package --archive="linux.zip" --include=minify --os=Linux

Note: To unpax a file on z/OS, go to the location where we want to unpax the file and then run the following command. The -ppx option is used to preserve the extended attributes.

    pax -ppx -rf location filename.pax

where location is the path where the file exists and filename.pax is the name of the file.


Package the Liberty runtime

In z/OS, use .pax instead of .zip for the following examples.

Create a runtime archive containing the wlp directory, but does not contain the usr directory. The naming convention for a server package is package_name.zip, such as in the following example: CustomerPortalApp.zip. To create a runtime archive, run the package command without a server name and with the --include=wlp option.

    server package --include=wlp

To specify a package file name and target location, add the --archive=package_path_name option.

    server package --include=wlp --archive=c:\temp\myPackage.zip

If we do not specify a valid package name or target location with the --archive option, then the command creates the wlp.zip runtime archive in the $WLP_OUTPUT_DIR location, which is the ${wlp.install.dir}/usr/servers directory by default. The target location must exist before running the command. Thus, if the target location is c:\temp, the C:\temp directory must exist and have write permission for the command to write the archive to the C:\temp directory.