Deploying applications in Liberty

You can deploy web applications, enterprise applications, and OSGi applications in Liberty. You deploy an application either by adding an application entry to the server configuration or by dropping the application into a previously defined dropins directory.

Deploying an application by using the dropins directory is not recommended for production environments, due to the restrictions this approach imposes.

Distributed: [AIX MacOS Linux Windows]You can also deploy applications to Liberty servers by using developer tools.

Before you begin

Do not disable dynamic updates to the runtime configuration. For more information, see Controlling dynamic updates.

About this task

Your application can be packaged as an archive file, a directory, or as a loose application, in which files are in multiple locations. For more information about loose applications, see Loose applications.

For more information about the default directory structure and the properties that are associated with directories, such as server.config.dir, see Liberty: Directory locations and properties.

The following procedure describes options to deploy an application either by configuring it in your server.xml file or by adding it to the dropins directory. Although deploying an application by using the dropins directory is useful in development environments, this approach is not recommended for production environments for the following reasons.
  • When an application archive is in the dropins directory, an unexpected file system event that touches the application archive file might cause the application to be restarted unnecessarily.
  • System resources are used to scan archives in the dropins directory for updates, which can impact performance.
  • Using the dropins directory might result in unnecessary cache updates, which might result in slower startup time. Instead, defining an application in the application element in the server.xml file results in more consistent caching of application resources across restarts.

Procedure

  • Deploy an application by adding it to the server configuration file.
    Configure the application element in the server.xml file. For more information, see the application element documentation. You must configure the following attributes for the application:
    id
    Must be unique and is used internally by the server.
    name
    Must be unique and depending on the application. The value of name might be used as the context-root of the application. For more information about how the context-root is set for an application, see Deploying a web application to Liberty.
    type
    Specifies the type of application.
    • For web applications, the supported type is war.
    • For enterprise applications, the supported type is ear.
    • For OSGi applications, the supported types are eba and esa.
    • For Spring Boot applications, the supported type is spring.
    location
    Specifies the location of the application. It can be an absolute path or a URL that you can download the application from. It can also be the file name of your application (including file extension if any).

    If the application is available on the file system, the location can either be the full path name or a simple file name. If the location does not include the full path, the application manager looks for the application in ${server.config.dir}/apps and ${shared.app.dir}. If the application is available at a URL, the application manager downloads the application to a temporary folder inside the server work area, then starts the application.

    Note: The location that you specify for a configured application must not be in the dropins directory. If you drop an application into the dropins directory, and also specify the location in the server.xml file, you are telling the server to deploy the application twice.
    In the following two examples, the location is the file system. If the location is a URL, enter the URL in the location field.
    <osgiApplication location="D:/apps/ImpactEBA.eba"/>
<webApplication location="ImpactWeb.war"/>
    The second example does not include the full path. In this case, you must put the application in one of the following locations:
    • ${server.config.dir}/apps (that is, server_directory/user/servers/server_name/apps)
    • ${shared.app.dir} (that is, liberty_install_location/usr/shared/apps)
    You can deploy your application to the file system in either of the following ways:
    • Place the archive file with its identifying suffix, such as .ear or .war, directly into the chosen location. For example, application_directory_path/myApp.war
    • Extract the archive file into a subdirectory of the chosen location, which is named with the application name and the identifying suffix. For example, application_directory_path/myApp.war/WEB-INF/...
    Note:
    • You must create the server-level apps directory, whereas the shared apps directory is present by default. See Liberty: Directory locations and properties for more information about the properties that are associated with the server directories.
    • The application element can be set before or after the server starts. If the element is set after the server starts, the changes are picked up dynamically.

    To remove applications that are included in the server configuration, remove the reference to the application from the server.xml file. The application is then automatically removed from the server.

  • Deploy an application by dropping it into the dropins directory.
    Note:
    • Restrictions apply when you use the dropins directory in a production environment. For more information, see the About this task section.

    For example, by using the default directory structure, to deploy an application you drop it into the ${server.config.dir}/dropins directory (that is, wlp/usr/servers/server_name/dropins).

    You can deploy your application in any of the following ways:
    • Place the archive file with its identifying suffix, such as .ear or .war, directly into the /dropins directory. For example, ${server.config.dir}/dropins/myApp.war
    • Extract the archive file into a directory that includes the application name and the identifying suffix. For example, ${server.config.dir}/dropins/myApp.war/WEB-INF/...
    • Place the archive file or the extracted archive into a subdirectory that includes the identifying suffix. For example, ${server.config.dir}/dropins/war/myApp/WEB-INF/...

    By default, the dropins directory is automatically monitored. If you drop an application into this directory, the application is automatically deployed on the server. If you modify an application in the dropins directory, the application is restarted unless the change is to a component of a WAR file outside of the WEB-INF folder.

    The dropins directory can be used for applications that do not require extra configuration, such as security role mapping. If you put your applications in the dropins directory, you must not include an entry for the application in the server configuration. Otherwise, the server tries to load the application twice and an error might occur. For applications that are not in the dropins directory, you specify the location by using an application entry in the server configuration.

    For applications in the dropins directory, the file name and file extension are used by the application monitor to determine the type of application, and to generate the application ID and application name. For example, if the archive file or directory is named snoop.war, the application monitor assumes that the application is a web application and that the application ID and application name are both snoop.

    To remove applications that are deployed to the dropins directory, delete the application from the directory. The application is then automatically removed from the server.

    To uninstall all applications that are in the dropins directory, set the application monitor dropinsEnabled property to false as described in Controlling dynamic updates.

What to do next

For all deployed applications, you can configure whether application monitoring is enabled and how often to check for updates to applications. For the dropins directory, you can also configure the name and location of the directory and choose whether to deploy the applications that are in the directory. For more information, see Controlling dynamic updates.