Packaging Liberty resources (deprecated)

Liberty resources can be packaged into one or more compressed (.zip) files for deployment by the WebSphere® Application Server Network Deployment Version 9.0 job manager. The grouping of the resources within the compressed files affects the scope and sharing of the resources. For resources in the compressed files to deploy correctly, the path names of the resources must satisfy job manager rules.

Before you begin

Packaging a Liberty server from the command prompt describes how to run the package command to create a compressed file that contains a Liberty runtime, files in the shared resources directory, one embedded server, and any applications embedded in the server. If you want to deploy a Liberty installation of this type and you do not need to place the installation in a project directory, consider using the package command to create the compressed file. For other types of Liberty installations, you must manually create one or more compressed files.

About this task

Supported Liberty resource types include project, runtime, Liberty server, application binary, and software development kit (SDK). For more information, read Liberty resources.

The job manager distinguishes between the different types of Liberty resources in a compressed file using the following rules:

  • The project resource is in an optional, top-level root directory in the compressed file. Subdirectories of this top-level root directory are the root of other resources. You can use the project resource to group related resources and to avoid name conflicts.
  • The runtime resource contains the file path runtime_name/bin/server or runtime_name/bin/server.bat. Everything under the runtime_name directory is considered part of the runtime resource.
  • The Liberty server resource satisfies one of the following rules:
    • If embedded within the runtime resource, the Liberty server resource contains the file path runtime_name/usr/servers/server_name/server.xml.
    • If isolated (separated) from the runtime resource, the Liberty server resource contains the file path servers/server_name/server.xml.
  • The application binary resource satisfies one of the following rules:
    • If embedded within the Liberty server resource, the application binary resource contains the file path server_name/dropins/application_name or server_name/apps/application_name, where application_name ends in .ear, .war, or .eba.
    • If embedded within the runtime resource, the application binary resource contains the file path runtime_name/usr/shared/apps/application_name, where application_name ends in .ear, .war, or .eba.
    • If isolated (separated) from the runtime and server resources, the application binary resource contains the application_name file in any directory path, where application_name ends in .ear, .war, or .eba.
  • The SDK resource contains the directory path JRE_name/jre/bin/java or JRE_name/bin/java, where JRE_name is the name of the Java runtime environment.
The job manager uses the directory name of a resource in the compressed file as its resource name. For example, if the directory name for the Liberty runtime is 08.05.00.00, then its resource name is 08.05.00.00, and its resource ID is runtime/08.05.00.00. When naming resources, consider the following guidelines:
  • If you are deploying a package to multiple operating systems, use directory and file names that are portable among operating systems. For example, do not name resources that differ only in capitalization so that you can deploy them to the Windows operating system; that is, do not mix jre-01.06.00 and Jre-01.06.00.
  • When using version numbers with major and minor numbers in resource names, such as 8.5.0.1, ensure that you allocate enough digits so that simple lexical string comparison can be used to compare versions. Use 08.05.00.01 instead of 8.5.0.1. This scheme works even if you use prefixes, such as runtime-08.05.00.01 or jre-01.06.00_32.

    Using this convention enables version comparison when querying for resources in the job manager. For example, in the job manager you might query for name > 08.05.00.11 to find all resources whose name, and version, is greater than 8.5.0.11. For an effective query, allocate at least two digits to each major and minor version number in the name. Otherwise, you get false results. For example, use 08.05.00.02 > 08.05.00.11 for a query instead of 8.5.0.2 > 8.5.0.11.

  • Use project names to group related resources and to avoid name conflicts.

Procedure

Determine the type of Liberty installation that you need, and then create one or more compressed (.zip) files that contain Liberty resources.

  • If you want to deploy from a Liberty installation that contains a Liberty runtime, files in the shared resources directory, one embedded server, and applications embedded in the server and you do not need to place the installation in a project directory, consider using the package command to create the compressed file.

    See the Liberty documentation for information about running the package command to create the compressed file.

  • If you want to deploy another type of Liberty installation, you must manually create one or more compressed files that contain Liberty resources.

    See the Example section for information about packaging of Liberty resources for specific deployment scenarios.

Example

The following examples illustrate the structure of Liberty resources for different deployment scenarios:
Example 1: Self-contained Liberty installation
This example first illustrates how to package a self-contained Liberty installation for deployment to one or more server hosts. It then illustrates how to package a new version of a server and the application that it supports.
The basic structure of the Liberty resources follows:
  • Server host
    • Working resources
      • Project
        • Liberty runtime
          • Liberty server 1
            • Application binary 1
          • Liberty server 2
            • Application binary 2
The following assumptions apply for this example installation:
  • The installation includes two servers.
  • Each server includes a bootstrap.properties file, a server.xml file, and one application.
  • Each server uses a previously installed SDK (JRE) that meets the minimum requirements for the Liberty. If you plan to use the job manager to install an SDK, see Example 2 for relevant packaging and server configuration information.
  • The Liberty installation is deployed to project directory samples in working directory /liberty/working, such as /liberty/working/samples.
Structure when deployed
This example Liberty installation has the following directory structure on the server hosts:
[-] liberty
    [-] working
        [-] samples
            [-] wlp-08.05.00.00
                [+] bin
                [ ] clients
                [+] dev
                [ ] lafiles
                [+] lib
                [+] templates
                [-] usr
                    [-] servers
                        [-] SecuritySample-01.00-01
                                o bootstrap.properties
                                o server.env
                                o server.xml
                            [ ] apps
                                    o SecuritySample-01.00.war
                        [-] ServletSample-01.00-01
                                o bootstrap.properties
                                o server.env
                                o server.xml
                            [ ] apps
                                    o ServletSample-01.00.war
Structure of package for initial deployment
The following directories and files are included in the compressed (.zip) file for initial deployment of the Liberty installation. The project directory, samples, is located at the root of the compressed file.
[-] samples
    [-] wlp-08.05.00.00
        [+] bin
        [ ] clients
        [+] dev
        [ ] lafiles
        [+] lib
        [+] templates
        [-] usr
            [-] servers
                [-] SecuritySample-01.00-01
                        o bootstrap.properties
                        o server.env
                        o server.xml
                    [ ] apps
                            o SecuritySample-01.00.war
                [-] ServletSample-01.00-01
                        o bootstrap.properties
                        o server.env
                        o server.xml
                    [ ] apps
                            o ServletSample-01.00.war
If a server must use an SDK (JRE) that is not the default, operating system-level JRE, you must specify the location of the appropriate JRE in a server.env file at the runtime or server level; for example:
JAVA_HOME=/opt/jre-06.00.31
Structure of package containing new version of server and application
The following directories and files are included in a compressed (.zip) file for a new version of a server and the application that it supports. The project directory, samples, is located at the root of the compressed file.
[-] samples
    [-] wlp-08.05.00.00
        [-] usr
            [-] servers
                [-] SecuritySample-01.01-01
                        o bootstrap.properties
                        o server.env
                        o server.xml
                    [ ] apps
                            o SecuritySample-01.01.war
Example 2: Host-level sharing of SDK and Liberty runtime
This example first illustrates how to package the Liberty resources for an environment where each server host includes a single shared instance of an SDK (JRE), a single shared instance of the Liberty runtime, and two isolated working servers that rely on the shared SDK and the shared Liberty runtime. It then illustrates how to package a new version of a server and the application that it supports. Use of the job manager is mandatory for environments that include isolated Liberty servers; you cannot use the Liberty server script to manage the servers.

For information about sharing server configuration settings at the host and network levels, see Liberty documentation about using includes in the configuration.

The basic structure of the Liberty resources follows. Using this approach helps to simplify maintenance and to conserve disk space as additional servers are deployed in the future.
  • Server hosts
    • Shared resources
      • SDK (JRE)
      • Liberty runtime
    • Working resources
      • Project
        • Liberty server 1
          • Application binary 1
        • Liberty server 2
          • Application binary 2
The following assumptions apply for this example installation:
  • The SDK (JRE) and the Liberty runtime are deployed to shared directory /liberty/shared.
  • The two isolated working servers are deployed to project directory samples in working directory /liberty/working, such as /liberty/working/samples. Including a project directory is optional.
  • Each server includes a bootstrap.properties file, a server.env file, a server.xml file, and one application.
Structure when deployed
This example Liberty environment has the following directory structure on each server host:
[-] liberty
    [-] shared
        [-] jre-06.00.31
            [+] bin
            [+] lib
        [-] wlp-08.05.00.00
            [+] bin
            [ ] clients
            [+] dev
            [ ] lafiles
            [+] lib
            [+] templates
    [-] working
        [-] samples
            [-] servers
                [-] SecuritySample-01.00-01
                        o bootstrap.properties
                        o server.env
                        o server.xml
                    [ ] apps
                            o SecuritySample-01.00.war
                [-] ServletSample-01.00-01
                         o bootstrap.properties
                         o server.env
                         o server.xml
                    [ ] apps
                            o ServletSample-01.00.war
Each isolated server is configured to use the shared SDK (JRE) and the shared Liberty runtime. The locations of the shared resources are stored in each server.env file; for example:
JAVA_HOME=${WLP_SHARED_DIR}/jre-06.00.31
WLP_RUNTIME_DIR=${WLP_SHARED_DIR}/wlp-08.05.00.00
The paths include the WLP_SHARED_DIR WebSphere variable instead of a hardcoded path. When the isolated servers are deployed to the server hosts, the job manager replaces ${WLP_SHARED_DIR} with the actual shared directory path, in this case /liberty/shared.
Structure of packages for initial deployment
The following directories and files are included in the compressed (.zip) file for initial deployment of the SDK (JRE) and the Liberty runtime to the shared resources directory that is defined by the WLP_SHARED_DIR WebSphere variable. Because it is likely that the SDK and the Liberty runtime will be used across projects, these resources are not included in a project directory. In this example, the SDK and the Liberty runtime are packaged into a single compressed file. However, you might package them into two separate compressed files, and submit two separate installation jobs.
[-] jre-06.00.31
    [+] bin
    [+] lib
[-] wlp-08.05.00.00
    [+] bin
    [ ] clients
    [+] dev
    [ ] lafiles
    [+] lib
    [+] templates

The following directories and files are included in the compressed (.zip) file for initial deployment of the Liberty servers and their applications to the working resources directory that is defined by the WLP_WORKING_DIR WebSphere variable. The project directory, samples, is located at the root of the compressed file.

[-] samples
    [-] servers
        [-] SecuritySample-01.00-01
                o bootstrap.properties
                o server.env
                o server.xml
            [ ] apps
                    o SecuritySample-01.00.war
        [-] ServletSample-01.00-01
                o bootstrap.properties
                o server.env
                o server.xml
            [ ] apps
                    o ServletSample-01.00.war
Structure of package to update server and application
The following directories and files are included in a compressed (.zip) file for later deployment of a new version of a server and its application to the working resources directory that is defined by the WLP_WORKING_DIR WebSphere variable. The project directory, samples, is located at the root of the compressed file.
[-] samples
    [-] servers
        [-] SecuritySample-01.01-01
                o bootstrap.properties
                o server.env
                o server.xml
            [ ] apps
                    o SecuritySample-01.01.war
Example 3: Network-level sharing of SDK, runtime, and applications
Restriction: Example 3 does not work on the Windows operating system.

This example first illustrates how to package the Liberty resources for an environment where the SDK (JRE), the Liberty runtime, and several applications are stored on shared disk, and two isolated (working) servers are stored on each server host. It then illustrates how to package a new version of a server and the application that it supports. Use of the job manager is mandatory for environments that include isolated Liberty servers. You cannot use the Liberty server script to manage the servers. For information about sharing server configuration settings at the host and network levels, see Liberty documentation about using includes in the configuration.

The basic structure of the Liberty resources follows. Using this approach helps to simplify maintenance and to conserve disk space when additional servers are deployed in the future.
  • Shared disk
    • Shared resources
      • SDK (JRE)
      • Liberty runtime
      • Application binary 1
      • Application binary 2
  • Server hosts
    • Working resources
      • Project
        • Liberty server 1
        • Liberty server 2
The following assumptions apply for this example installation:
  • The SDK (JRE), Liberty runtime, and applications are installed to shared disk at path /liberty/shared.
  • On each server host, the shared resources directory (on shared disk) is mounted at the same path, /liberty/shared.
  • On each server host, the two isolated (working) servers are deployed to project directory samples in working directory /liberty/working, such as /liberty/working/samples. Including a project directory is optional.
  • Each server includes a bootstrap.properties file, a server.env file, and a server.xml file.
Structure when deployed
This example Liberty environment has the following directory structures on shared disk and on the server hosts:
Shared disk

[-] liberty
    [-] shared
        [-] jre-06.00.31
            [+] bin
            [+] lib
        [-] wlp-08.05.00.00
            [+] bin
            [ ] clients
            [+] dev
            [ ] lafiles
            [+] lib
            [+] templates
        [-] samples
            [ ] apps
                    o SecuritySample-01.00.war
                    o ServletSample-01.00-01.war
Server hosts

[-] liberty
    [-] working
        [-] samples
            [-] servers
                [-] SecuritySample-01.00-01
                        o bootstrap.properties
                        o server.env
                        o server.xml
                [-] ServletSample-01.00-01
                         o bootstrap.properties
                         o server.env
                         o server.xml
Each isolated server is configured to use the shared SDK (JRE) and the shared Liberty runtime. The locations of the shared resources are stored in each server.env file; for example:
JAVA_HOME=${WLP_SHARED_DIR}/jre-06.00.31
WLP_RUNTIME_DIR=${WLP_SHARED_DIR}/wlp-08.05.00.00
The paths include the WLP_SHARED_DIR WebSphere variable instead of a hardcoded path. When the isolated servers are deployed to the server hosts, the job manager replaces ${WLP_SHARED_DIR} with the actual shared directory path, in this case /liberty/shared. On each server host, the remote shared resources directory is mounted at /liberty/shared.
Because the applications are in shared storage that is apart from the servers, the application element in each server.xml file must include the full path to the corresponding WAR file; for example:
<application id="SecuritySample"
             location="/liberty/shared/apps/SecuritySample-01.00.war"
             name="SecuritySample" type="war"/>
To minimize changes to the server.xml file, the application directory and version information can be stored in two properties in each server bootstrap.properties file; for example:
apps.dir=${WLP_SHARED_DIR}/${CURRENT_PROJECT}/apps 
security.sample.version=1.00
You then can include both the WLP_SHARED_DIR WebSphere variable and the CURRENT_PROJECT built-in job manager variable in the application element in each server.xml file; for example:
<application id="SecuritySample" 
             location="${apps.dir}/SecuritySample-${security.sample.version}.war"
             name="SecuritySample" type="war"/>
Structure of packages for initial deployment
The following directories and files are included in the compressed (.zip) file for initial deployment of the SDK (JRE), Liberty runtime, and applications to the shared disk location that is defined by the WLP_SHARED_DIR WebSphere variable. Because it is likely that the SDK and the Liberty runtime will be shared across projects, these resources are not included in a project directory. The applications are included in project directory samples. In this example, you package all the shared resources into a single compressed file. However, you might package them into three separate compressed files, and submit three separate installation jobs.
[-] jre-06.00.31
    [+] bin
    [+] lib
[-] wlp-08.05.00.00
    [+] bin
    [ ] clients
    [+] dev
    [ ] lafiles
    [+] lib
    [+] templates
[-] samples
    [ ] apps
            o SecuritySample-01.00.war
            o ServletSample-01.00.war

The following directories and files are included in a compressed (.zip) file for initial deployment of the Liberty servers to the working resources directory that is defined by the WLP_WORKING_DIR WebSphere variable:

[-] samples
    [-] servers
        [-] SecuritySample-01.01-01
                o bootstrap.properties
                o server.env
                o server.xml
        [ ] ServletSample-01.00-01
                o bootstrap.properties
                o server.env
                o server.xml
Structure of packages for update to application and server
The following directories and files are included in a compressed (.zip) file for later deployment of a new version of an application to the shared disk location that is defined by the WLP_SHARED_DIR WebSphere variable. The project directory, samples, is located at the root of the file:
[-] samples
    [ ] apps
            o SecuritySample-01.01.war

The following directories and files are included in a compressed (.zip) file for later deployment of a new version of a server to the working resources directory that is defined by the WLP_WORKING_DIR WebSphere variable. The project directory, samples, is located at the root of the compressed file.

[-] samples
    [-] servers
        [-] SecuritySample-01.01-01
                o bootstrap.properties
                o server.env
                o server.xml

You must change the application element in the server.xml file to include Version 1.01 of the WAR file; for example:

<application id="SecuritySample"
             location="/liberty/shared/apps/SecuritySample-01.01.war"
             name="SecuritySample" type="war"/>

Alternatively, if the bootstrap.properties file contains the application version information, you must change the file accordingly; for example:

security.sample.version=1.01

You then use the updated version information in the application element in the server.xml file; for example:

<application id="SecuritySample" 
             location="${apps.dir}/SecuritySample-${security.sample.version}.war"
             name="SecuritySample" type="war"/>

What to do next

Set variables that enable the job manager to install and search for Liberty resources.