Installing on WebSphere
Installing Liferay DXP on WebSphere requires installing the DXP WAR, installing dependencies, configuring WebSphere, and starting DXP. You must also configure your database and mail server connections.
IBM® WebSphere® is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.
Throughout this installation and configuration process, WebSphere prompts you to click Save to apply changes to the Master Configuration. It is necessary to do so to save the changes.
For Liferay DXP to work correctly, WebSphere 9 (Fix Pack 11 or newer) must be installed. Go to IBM Support to find out more information about this fix pack. Liferay DXP does not currently support the WebSphere Application Liberty Profile.
Before installing DXP, please review the Installing a Liferay-Tomcat Bundle and Configuring a Database articles.
The following files are required to install Liferay DXP on the WebSphere application server and are available from the Help Center (subscription) or from Liferay Community Downloads:
- DXP WAR file
- OSGi Dependencies ZIP file
- Dependencies ZIP file (DXP 7.3 and earlier)
Liferay DXP requires a Java JDK 8 or 11. See the compatibility matrix to choose a JDK. See JVM Configuration for recommended settings.
[Liferay Home] folder is where Liferay DXP stores and manages files and folders required to function. On WebSphere, the
[Liferay Home] folder is typically
Creating a WebSphere Profile
When the application server binaries have been installed, start the Profile Management Tool to create a profile appropriate for DXP.
Click Create…, choose Application Server, and then click Next.
Click the Advanced profile creation option and then click Next. Use the advanced profile to specify the values for settings such as the location of the profile and names of the profile, node and host, to assign specific ports, or to optionally choose whether to deploy the administrative console and sample application and also add web-server definitions for IBM HTTP Server. See the WebSphere documentation for more information about these options.
Check the box Deploy the administrative console. This enables a web-based UI for working with the application server. Skip the default applications. (Install these only on a development machine.) Click Next.
Set the profile name and location. Specify a performance tuning settings appropriate for your environment.note
See the WebSphere documentation for more information about performance tuning settings. Click Next.
Choose node, server, and host names for the server. These are specific to a user’s environment. Click Next.
Administrative security in WebSphere is a way to restrict who has access to the administrative tools. You may want to have it enabled in the environment so that a user name and password are required to administer the WebSphere server. See WebSphere’s documentation for more information. Click Next.
Each profile needs a security certificate, which comes next in the wizard. If the certificates are not already generated, choose the option to generate a personal certificate and a signing certificate and click Next.
Once the certificates are generated, set a password for the keystore. Click Next.
You can customize the ports this server profile uses. Be sure to choose ports that are open on the machine. When choosing ports, the wizard automatically detects existing WebSphere installations and if it finds activity, will increment ports by one.
Choose whether to start this profile when the machine starts. Click Next.
WebSphere ships with IBM HTTP Server. Choose whether you want a web server definition, so that this JVM receives requests forwarded from the HTTP server. See WebSphere’s documentation for details on this. When finished, click Next.
The wizard then displays a summary of what was selected, enabling you to keep your choices or go back and change something. When finished, click Next.
WebSphere then creates the profile and finishes with a message indicating that the profile was created successfully.
Lastly, shut down the application server.
Configuring the WebSphere Application Server
Do not make configuration changes while the application server is running.
In this version of WebSphere, servlet filters are not initialized on web application startup, but rather, on first access. This can cause problems when deploying certain apps to DXP. To configure servlet filters to initialize on application startup (i.e., deployment), set the following
webcontainer properties in the WebSphere application server:
com.ibm.ws.webcontainer.initFilterBeforeInitServlet = true com.ibm.ws.webcontainer.invokeFilterInitAtStartup = true
webcontainer properties in the WebSphere application server, follow the instructions in WebSphere’s documentation.
Setting up JVM Parameters for Liferay DXP
Start with modifying this file:
As a baseline, add
maximumHeapSize="2560" inside the
jvmEntries tag. For example:
<jvmEntries xmi:id="JavaVirtualMachine_1183122130078" ... maximumHeapSize="2560">
After installing DXP, these configurations (including these JVM options) can be further tuned for improved performance. Please see Tuning Liferay and Tuning Your JVM for more information.
You can set the UTF-8 properties in the
<jvmEntries genericJvmArguments=.../> attribute in
server.xml. This is required or else international characters will not be parsed correctly. Increase the maximum and minimum heap sizes there too. Add the following inside the
<jvmEntries xmi:id="JavaVirtualMachine_1183122130078" ...genericJvmArguments="-Dfile.encoding=UTF-8 -Djava.locale.providers=JRE,COMPAT,CLDR -Djava.net.preferIPv4Stack=true -Dlog4j2.formatMsgNoLookups=true -Duser.timezone=GMT -Xms6144m -Xmx6144m -XX:MaxNewSize=1536m -XX:MaxMetaspaceSize=768m -XX:MetaspaceSize=768m -XX:NewSize=1536m -XX:SurvivorRatio=7">
For DXP to work properly, the application server JVM must use the
GMT time zone and
UTF-8 file encoding.
The Java options and memory arguments are explained below.
JVM Options Explained
||DXP requires UTF-8 file encoding.|
||This is required for displaying four-digit dates on JDK 11.|
||Prefers an IPv4 stack over IPv6.|
||Resolves a remote code execution (RCE) vulnerability. See LPS-143663 for details.|
||DXP requires the application server JVM to use the GMT time zone.|
Memory Arguments Explained
||Initial space for the heap.|
||Maximum space for the heap.|
||Initial new space. Setting the new size to half of the total heap typically provides better performance than using a smaller new size.|
||Maximum new space.|
||Initial space for static content.|
||Maximum space for static content.|
||Ratio of the new space to the survivor space. The survivor space holds young generation objects before being promoted to old generation space.|
In the same profile, delete a problematic
secureSessionCookie tag that can cause DXP startup errors. Note, this is just a default setting; once DXP is installed, tune WebSphere appropriately based on your usage.
[Install Location]/WebSphere/AppServer/profiles/your-profile/config/cells/your-cell/cell.xml, delete the
secureSessionCookie tag containing
If this tag is not removed, an error similar to this may occur:
WSVR0501E: Error creating component [email protected] com.ibm.ws.exception.RuntimeWarning: com.ibm.ws.webcontainer.exception.WebAppNotLoadedException: Failed to load webapp: Failed to load webapp: SRVE8111E: The application, LiferayEAR, is trying to modify a cookie which matches a pattern in the restricted programmatic session cookies list [domain=*, name=JSESSIONID, path=/].
By this point, the following steps should be completed:
- The WebSphere Application Server profile has been created.
- Servlet filters have been configured to initialize on application startup in the
- The JVM parameters have been set in the
- UTF-8 has been set as the file encoding.
- The server’s time zone is set to GMT.
secureSessionCookietag has been removed.
Unzip the OSGi Dependencies ZIP file and place its contents in the
[Liferay Home]/osgifolder (create this folder if it doesn’t already exist). Liferay’s OSGi runtime depends on these modules.
The DXP 7.4+ WAR file includes drivers for MariaDB and PostgreSQL. Earlier DXP WARs don’t have them. If the 7.4+ WAR doesn’t have the driver for the supported database you’re using, unzip the DXP WAR to an arbitrary location, place your database vendor’s JDBC JAR file in the exploded DXP WAR’s
WEB-INF/shielded-container-libfolder, and ZIP up the DXP WAR again.
Please see the compatibility matrix for a list of supported databases.
A Hypersonic database is bundled with DXP and is useful for testing purposes. Do not use HSQL for production instances.
For DXP 7.3 and earlier, Unzip the Dependencies ZIP file and place its contents in the WebSphere application server’s
[Install Location]/WebSphere/AppServer/lib/ext folder. Place your database vendor’s JDBC JAR file in that folder too.
When you start Liferay, it installs and starts a default sidecar Elasticsearch server. When installing on WebSphere you should set up a remote Elasticsearch server right from the start. See Getting Started with Elasticsearch.
When Liferay DXP is configured (using
.config files for the Elasticsearch connctor) and started with Elasticsearch already configured and running, the connection to Elasticsearch is activated.
Installing the DXP portlet.jar
portlet.jar (version 3) is backwards-compatible with version 2.0. The DXP 7.4
.war includes the
portlet.jar and the Dependencies ZIP for earlier DXP versions include it too. WebSphere’s
portlet.jar version 2.0 must be overridden.
[Install Location]/WebSphere/AppServer/profiles/your-profile/folder, create a folder called
Copy the DXP
portlet.jarfrom your DXP WAR (7.4+) or from the
[Install Location]/WebSphere/AppServer/lib/extfolder to the
app_shared_librariesfolder you created.
Follow IBM’s steps for using a server-associated shared library; make sure to choose Classes loaded with local class loader first (parent_Last) on step 4d.
Save the configuration.
Ensuring That the DXP Portlet.jar is Loaded First
In addition to placing DXP’s
portlet.jar in a server-associated shared library, configure the
config.ini file so that it is loaded first.
- Open the
- Find the property
- Insert the property
- Save the file.
- DXP dependencies have been installed.
portlet.jarhas been installed.
config.inifile has been configured.
Start the application server profile.
DXP contains a built-in Hypersonic database which is great for demonstration purposes but should not be used in production. Beyond demonstration purposes, we recommend using a full-featured, supported RDBMS. See Configuring a Database to set up the database.
Liferay DXP can connect with your database using DXP’s built-in data source (recommended) or using a data source you create on your app server.
To configure DXP’s built-in data source with your database when you run DXP for the first time, use the Setup Wizard. Or you can configure the data source in a
portal-ext.properties file based on the Database Template for your database.
If using WebSphere to manage the database connections, follow the instructions below. Otherwise, skip this section if you plan to use DXP’s built in data source.
Liferay uses HSQL by default for demo purposes. HSQL should not be used in production instances of Liferay DXP.
Get the JDBC JAR from your DXP WAR (7.4+) or from the database vendor, and copy it to the
Open the Administrative Console and log in.
Click Resources → JDBC Providers.
Select a scope and then click New.
Select the database type, provider type, and implementation type. If selecting a predefined database, the wizard fills automatically in the name and description fields. If the desired database isn’t listed, select User-defined from the Database type field and then fill in the Implementation Class Name. For example, if using MySQL, select Database type → User-defined, and then enter
com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSourcein Implementation Class Name. Click Next.
Clear any text in the class path settings. The necessary JARs have already been copied to a location on the server’s class path. Click Next.
Review the settings and click Finish. The final configuration should look like this:
Click the new provider configuration when it appears in the table.
Click Data Sources under Additional Properties.
liferaydatabasesourcein the Data source name field and
jdbc/LiferayPoolin the JNDI name field. Click Next.
Click Next in the remaining screens of the wizard to accept the default values. Then review all the changes and click Finish.
Click the data source when it appears in the table and then click Custom Properties.
Click the Show Filter Function button. This is the second from last of the small icons under the New and Delete buttons.
Enter user into the search terms and click Go.
Select the user property and give it the value of the user name to the database.
Click OK and save to master configuration.
Do another filter search for the url property. Give this property a value that points to the database. For example, a MySQL URL would look like this:
For more example URLs, see the
jdbc.default.urlvalues in Database Templates.
Click OK and save to master configuration.
Do another filter search for the password property. Enter the password for the user ID added earlier as the value for this property. Click OK and save to master configuration.
Go back to the data source page by clicking it in the breadcrumb trail. Use the Test Connection button to validate configurations to this point.
portal-ext.propertiesfile in [Liferay_Home], specify the data source. For example,
If using DXP’s built-in mail sessions, skip this section. See the Configuring Mail article on how to use DXP’s built-in mail sessions.
If you want to use WebSphere to manage the mail session, follow these steps:
Creating a WebSphere-Managed Mail Session
Click Resources → Mail → Mail Providers.
Click the Built-In Mail Provider for the node and server.
Click Mail Sessions and then click the New button.
Give the mail session a name of
liferaymailand a JNDI name of
mail/MailSession. Fill in the correct information for your mail server in the sections Outgoing Mail Properties and Incoming Mail Properties. Click OK and then save to the master configuration.
Click the mail session when it appears in the table and select Custom Properties under the Additional Properties section. Set any other JavaMail properties required by the mail server, such as the protocol, ports, whether to use SSL, and so on.
Click Security → Global Security and de-select Use Java 2 security to restrict application access to local resources if it is selected.
portal-ext.propertiesfile in Liferay Home, specify the mail session. For example,
Note that it might be necessary to retrieve a SSL certificate from mail server and add it to WebSphere’s trust store. See WebSphere’s documentation for instructions on this.
Verifying WebSphere Mail Provider
To validate that the mail session has been configured correctly, there are a number of ways to test this once the WAR has been deployed, the server has started, and the user has signed in as the system administrator. One quick way to validate is to create a new user with a valid email account. The newly created user should receive an email notification. The logs should display that the SMTP server has been pinged with the correct port number listed.
Enable Cookies for HTTP Sessions
WebSphere restricts cookies to HTTPS sessions by default. If using HTTP, this prevents users from signing in to DXP and displays the following error in the console:
20:07:14,021 WARN [WebContainer : 1][SecurityPortletContainerWrapper:341] User 0 is not allowed to access URL http://localhost:9081/web/guest/home and portlet com_liferay_login_web_portlet_LoginPortlet
This occurs because DXP cannot use the HTTPS cookie when using HTTP. The end result is that new sessions are created on each page refresh. Follow these steps to resolve this issue in WebSphere:
- Click Application Servers → server1 → Session Management → Enable Cookies.
- De-select Restrict cookies to HTTPS sessions.
- Click Apply.
- Click Save.
In WebSphere’s administrative console, click Applications → New Application → New Enterprise Application.
Browse to the DXP
.warfile, select it, and click Next.
Leave Fast Path selected and click Next. Ensure that Distribute Application has been checked and click Next again.
Choose the WebSphere runtimes and/or clusters where DXP is to be deployed. Click Next.
Select the virtual host to deploy DXP on and click Next.
Map DXP to the root context (
/) and click Next.
Select the desired metadata-complete attribute setting and click Next.
Verify that the settings are correct and click Finish.
When DXP has installed, click Save to Master Configuration.
DXP has been installed. There are a few more required steps before starting DXP.
Setting the JDK Version for Compiling JSPs
DXP requires that its JSPs are compiled to the Java 8 bytecode format. To ensure that WebSphere does this, shut down WebSphere after you’ve deployed the DXP
.war file. Navigate to the
WEB_INF folder and add the following setting to the
ibm-web-ext.xml or in most cases the
<jsp-attribute name="jdkSourceLevel" value="18" />
The exact path to the
ibm-web-ext.xmi file depends on the WebSphere installation location and DXP version, but here’s an example:
Note that the DXP
.war comes pre-packaged with the
ibm-web-ext.xmi file; this format is functionally the same as
.xml and WebSphere recognizes both formats. For more general information on how WebSphere compiles JSPs see IBM’s official documentation for WebSphere Application Server 9.0.0.x.
If you want to use the Setup Wizard, skip to the next step. However, if your are using WebSphere’s data source and mail session and you want to bypass the Setup Wizard, set this portal property in your
Start the application server.
In the WebSphere administrative console, navigate to Enterprise Applications, select the DXP application, and click Start. While DXP is starting, WebSphere displays a spinning graphic.
In DXP’s setup wizard, select and configure the database type. Click Finish. DXP then creates the tables it needs in the database.
After deploying DXP, there may be excessive warnings and log messages, such as the ones below, involving
PhaseOptimizer. These are benign and can be ignored. Make sure to adjust the app server’s logging level or log filters to avoid excessive benign log messages.
If you have a Liferay DXP Enterprise subscription, DXP requests your activation key. See Activating Liferay DXP for more information.
Congratulations! You’re running Liferay DXP on WebSphere.
You can sign in as your administrator user and start building a solution on DXP. Or you can explore additional Liferay DXP setup topics: