Installing Liferay DXP on WebSphere

IBM ® WebSphere ® is a trademark of International Business Machines Corporation, registered in many jurisdictions worldwide.

Tip: Throughout this installation and configuration process, WebSphere prompts you to click Save to apply changes to the Master Configuration. Do so intermittently to save your changes.

For Liferay DXP to work correctly, WebSphere 8.5.5 Fix Pack 11 (or later) or WebSphere 9 (Fix Pack 7 is the latest) must be installed. You can find more information about this fix pack here.

Please also note that Liferay DXP doesn’t support the WebSphere Application Liberty Profile.

You should also read the following articles to familiarize yourself with Liferay DXP’s general installation steps:

• Preparing for Install
• Installing Liferay DXP

Note that the Liferay Home folder is important to the operation of Liferay DXP. In Liferay Home, Liferay DXP creates certain files and folders that it needs to run. On WebSphere, Liferay Home is typically [Install Location]/WebSphere/AppServer/profiles/your-profile/liferay.

Before proceeding, you must download these Additional Files for DXP or Portal CE::

• Liferay DXP WAR file
• Dependencies ZIP file
• OSGi Dependencies ZIP file

Liferay DXP requires a Java JDK 8 or 11.

Note: Please see the compatibility matrix for information on supported JDKs, databases, and environments.

Without any further ado, get ready to install Liferay DXP in WebSphere!

Preparing WebSphere for Liferay DXP

When the application server binaries have been installed, start the Profile Management Tool to create a profile appropriate for Liferay DXP.

1. Click Create…, choose Application Server, and then click Next.

2. Click the Advanced profile creation option and then click Next. You need the advanced profile to specify your own values for settings such as the location of the profile and names of the profile, node and host, to assign your own 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.

   

   Figure 1: Choose the Advanced profile option to specify your own settings.

3. Check the box Deploy the administrative console. This gives you a web-based UI for working with your application server. Skip the default applications. You’d only install these on a development machine. Click Next.

4. Set the profile name and location. Ensure you specify a performance tuning setting other than Development, since you’re installing a production server. See the WebSphere documentation for more information about performance tuning settings. Click Next.

5. Choose node, server, and host names for your server. These are specific to your environment. Click Next.

6. Administrative security in WebSphere is a way to restrict who has access to the administrative tools. You may want to have it enabled in your environment so that a user name and password are required to administer the WebSphere server. See WebSphere’s documentation for more information. Click Next.

7. Each profile needs a security certificate, which comes next in the wizard. If you don’t have certificates already, choose the option to generate a personal certificate and a signing certificate and click Next.

8. Once the certificates are generated, set a password for your keystore. Click Next.

9. Now you can customize the ports this server profile uses. Be sure to choose ports that are open on your machine. When choosing ports, the wizard detects existing WebSphere installations and if it finds activity, it increments ports by one.

10. Choose whether you want this profile started when the machine starts. Click Next.

11. WebSphere ships with IBM HTTP Server, which is a re-branded version of Apache. 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.

12. The wizard then shows you a summary of what you selected, enabling you to keep your choices or go back and change something. When you’re satisfied, click Next.

WebSphere then creates your profile and finishes with a message telling you the profile was created successfully. Awesome! Your profile is complete. Now there are a few things you need to configure in your application server.

Figure 2: Example of the settings before creating the profile.

Configuring the WebSphere Application Server

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 Liferay DXP. To configure servlet filters to initialize on application startup (i.e., deployment), set the following webcontainer properties in your WebSphere application server:

com.ibm.ws.webcontainer.initFilterBeforeInitServlet = true
com.ibm.ws.webcontainer.invokeFilterInitAtStartup = true

To set webcontainer properties in the WebSphere application server, follow the instructions here in WebSphere’s documentation.

Setting up JVM Parameters for Liferay DXP

Next, in the WebSphere profile you created for Liferay DXP, you must set an argument that supports Liferay DXP’s Java memory requirements. You’ll modify this file:

[Install Location]/WebSphere/AppServer/profiles/your-profile/config/cells/your-cell/nodes/your-node/servers/your-server/server.xml

Add maximumHeapSize="2048" inside the jvmEntries tag. For example:

<jvmEntries xmi:id="JavaVirtualMachine_1183122130078" ... maximumHeapSize="2048">

Note: The JVM parameters used here are defaults intended for initial deployment of production systems. Administrators should change the settings to values that best address their specific environments. These must be tuned depending on need.

Administrators can set the UTF-8 properties in the server.xml file. This is required or else special characters will not be parsed correctly. Add the following inside the jvmEntries tag:

<jvmEntries xmi:id="JavaVirtualMachine_1183122130078" ...genericJvmArguments="-Dfile.encoding=UTF-8 -Duser.timezone=GMT">

Important: For Liferay DXP to work properly, the application server JVM must use the GMT time zone and UTF-8 file encoding.

Alternately, you can set the UTF-8 properties from the WebSphere Admin Console. (See below.)

Important: On JDK 11, the setting -Djava.locale.providers=JRE,COMPAT,CLDR is required to display four-digit years. Since JDK 9, the Unicode Common Locale Data Repository (CLDR) is the default locales provider. CLDR does not provide years in a four-digit format (see LPS-87191). This setting works around the issue by using JDK 8’s default locales provider.

Removing the secureSessionCookie Tag

In the same profile, you should delete a problematic secureSessionCookie tag that can cause Liferay DXP startup errors. Note that this is just a default setting; once Liferay DXP is installed, you should tune it appropriately based on your usage.

In [Install Location]/WebSphere/AppServer/profiles/your-profile/config/cells/your-cell/cell.xml, Delete the secureSessionCookie tag containing xmi:id="SecureSessionCookie_1".

If this tag is not removed, an error similar to this may occur:

WSVR0501E: Error creating component com.ibm.ws.runtime.component.CompositionUnitMgrImpl@d74fa901    
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=/].

Installing Liferay DXP’s Dependencies

You must now install Liferay DXP’s dependencies. Recall that earlier you downloaded two ZIP files containing these dependencies. Install their contents now:

1. liferay-dxp-dependencies-[version].zip: Unzip this file and place its contents in your WebSphere application server’s [Install Location]/WebSphere/AppServer/lib/ext folder. If you have a JDBC database driver JAR, copy it to this location as well.

2. liferay-dxp-osgi-[version].zip: Unzip this file and place its contents in the [Liferay Home]/osgi folder (create this folder if it doesn’t exist). This is typically [Install Location]/WebSphere/AppServer/profiles/your-profile/liferay/osgi.

Installing the DXP portlet.jar

DXP’s portlet.jar (version 3) is backwards-compatible. It is included with the Dependencies ZIP that you unzipped above. WebSphere contains an older portlet.jar version which must be overridden.

1. In your [Install Location]/WebSphere/AppServer/profiles/your-profile/ folder, create a folder called app_shared_libraries.

2. Move DXP’s portlet.jar from the [Install Location]/WebSphere/AppServer/lib/ext folder to the app_shared_libraries folder you created.

3. 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.

4. 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.

1. Open the [Install Location]/WebSphere/AppServer/configuration/config.ini file.
2. Find the property com.ibm.CORBA,com.ibm.
3. Insert the property javax.portlet,javax.portlet.filter,javax.portlet.annotations after com.ibm.CORBA and before com.ibm.
4. Save the file.

Start the server profile you created for Liferay DXP. Once it starts, you’re ready to configure your database.

Database Configuration

If you want WebSphere to manage the database connections, follow the instructions below. Note this is not necessary if you plan to use Liferay DXP’s standard database configuration; in that case, skip this section. You’ll set your database information in Liferay DXP’s setup wizard after the install.

Note: Although Liferay DXP’s embedded database is fine for testing purposes, you should not use it for production Liferay DXP instances.

Figure 3: WebSphere JDBC providers

1. Start WebSphere.

2. Open the Administrative Console and log in.

3. Click Resources → JDBC Providers.

4. Select a scope and then click New.

5. Select your database type, provider type, and implementation type. If you select a predefined database, the wizard fills in the name and description fields for you. If the database you want to use isn’t listed, select User-defined from the Database type field and then fill in the Implementation Class Name. For example, if you use MySQL, select Database type → User-defined, and then enter com.mysql.jdbc.jdbc2.optional.MysqlConnectionPoolDataSource in Implementation Class Name. Click Next when you are finished.

6. Clear any text in the classpath settings. You already copied the necessary JARs to a location on the server’s classpath. Click Next.

7. Review your settings and click Finish. The final configuration should look like this:

   

   Figure 4: Completed JDBC provider configurations.

8. Click your new provider configuration when it appears in the table, and then click Data Sources under Additional Properties. Click New.

9. Enter liferaydatabasesource in the Data source name field and jdbc/LiferayPool in the JNDI name field. Click Next.

10. Click Next in the remaining screens of the wizard to accept the default values. Then review your changes and click Finish.

11. Click the data source when it appears in the table and then click Custom Properties. Now click the Show Filter Function button. This is the second from last of the small icons under the New and Delete buttons.

12. Type user into the search terms and click Go.

    

    Figure 5: Modifying data source properties in WebSphere

13. Select the user property and give it the value of the user name to your database. Click OK and save to master configuration.

14. Do another filter search for the url property. Give this property a value that points to your database. For example, a MySQL URL would look like this:

    jdbc:mysql://localhost/lportal?useUnicode=true&characterEncoding=UTF-8&useFastDateParsing=false
    

    Click OK and save to master configuration.

15. Do another filter search for the password property. Enter the password for the user ID you added earlier as the value for this property. Click OK and save to master configuration.

16. Go back to the data source page by clicking it in the breadcrumb trail. Click the Test Connection button. It should connect successfully.

Once you’ve set up your database, you can set up your mail session.

Mail Configuration

If you want WebSphere to manage your mail sessions, use the following procedure. If you want to use Liferay DXP’s built-in mail sessions, you can skip this section.

Creating a WebSphere-Managed Mail Session (Optional)

1. Click Resources → Mail → Mail Providers.

2. Click the Built-In Mail Provider for your node and server.

3. Click Mail Sessions and then click the New button.

4. Give your mail session a name of liferaymail and 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.

5. Click your mail session when it appears in the table and select Custom Properties under the Additional Properties section. Set any other JavaMail properties required by your mail server, such as the protocol, ports, whether to use SSL, and so on.

6. Click Security → Global Security and de-select Use Java 2 security to restrict application access to local resources if it is selected. Click Apply.

Note that you may also need to retrieve a SSL certificate from your 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 you’re using HTTP instead, this prevents users from signing in to Liferay 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 Liferay DXP can’t use the HTTPS cookie when you use HTTP. The end result is that new sessions are created on each page refresh. Follow these steps to resolve this issue in WebSphere:

1. Click Application Servers → server1 → Session Management → Enable Cookies

2. De-select Restrict cookies to HTTPS sessions

3. Click Apply

4. Click Save

Enable UTF-8

If you did not add the -Dfile.encoding=UTF-8 property in the server.xml, you can do so in the Administrative Console.

1. Click Application Servers → server1 → Process definition.

2. Click Java Virtual Machine under Additional Properties.

3. Enter -Dfile.encoding=UTF-8 in the Generic JVM arguments field.

4. Click Apply and then Save to master configuration.

Once the changes have been saved, Liferay DXP can parse special characters if there is localized content.

Deploy Liferay DXP

Now you’re ready to deploy Liferay DXP!

1. In WebSphere’s administrative console, click Applications → New Application → New Enterprise Application.

2. Browse to the Liferay DXP .war file, select it, and click Next.

3. Leave Fast Path selected and click Next. Ensure that Distribute Application has been checked and click Next again.

4. Choose the WebSphere runtimes and/or clusters where you want Liferay DXP deployed. Click Next.

5. Select the virtual host to deploy Liferay DXP on and click Next.

6. Map Liferay DXP to the root context (/) and click Next.

7. Select the metadata-complete attribute setting that you want to use and click Next.

8. Ensure that you have made all the correct choices and click Finish. When Liferay DXP has installed, click Save to Master Configuration.

   

   Figure 6: Review your deployment options before deploying.

You’ve now installed Liferay DXP!

Setting the JDK Version for Compiling JSPs

Liferay 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 Liferay 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 ibm-web-ext.xmi file:

<jsp-attribute name="jdkSourceLevel" value="18" />

The exact path to the ibm-web-ext.xmi file depends on your WebSphere installation location and Liferay DXP version, but here’s an example:

/opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config/cells/localhostNode01Cell/applications/liferayXX.ear/deployments/liferayXX/liferayXX.war/WEB-INF/ibm-web-ext.xmi

Note that the Liferay 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 8.5.5.x or WebSphere Application Server 9.0.0.x.

Now restart WebSphere.

Start Liferay DXP

1. If you plan to use Liferay DXP’s setup wizard, skip to the next step. If you wish to use WebSphere’s data source and mail session, create a file called portal-ext.properties in your Liferay Home folder. Place the following configuration in the file:

    jdbc.default.jndi.name=jdbc/LiferayPool
    mail.session.jndi.name=mail/MailSession
    setup.wizard.enabled=false
   

2. In the WebSphere administrative console, navigate to Enterprise Applications, select the Liferay DXP application, and click Start. While Liferay DXP is starting, WebSphere displays a spinning graphic. Don’t watch it too closely, or you might get hypnotized.

3. In Liferay DXP’s setup wizard, select and configure your database type. Click Finish when you’re done. Liferay DXP then creates the tables it needs in the database.

Congratulations! You’ve installed Liferay DXP on WebSphere!

After deploying Liferay DXP, you may see excessive warnings and log messages, such as the ones below, involving PhaseOptimizer. These are benign and can be ignored. Make sure to adjust your app server’s logging level or log filters to avoid excessive benign log messages.

May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
WARNING: Skipping pass gatherExternProperties
May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
WARNING: Skipping pass checkControlFlow
May 02, 2018 9:12:27 PM com.google.javascript.jscomp.PhaseOptimizer$NamedPass process
INFO: pass supports: [ES3 keywords as identifiers, getters, reserved words as properties, setters, string continuation, trailing comma, array pattern rest, arrow function, binary literal, block-scoped function declaration, class, computed property, const declaration, default parameter, destructuring, extended object literal, for-of loop, generator, let declaration, member declaration, new.target, octal literal, RegExp flag 'u', RegExp flag 'y', rest parameter, spread expression, super, template literal, modules, exponent operator (**), async function, trailing comma in param list]
current AST contains: [ES3 keywords as identifiers, getters, reserved words as properties, setters, string continuation, trailing comma, array pattern rest, arrow function, binary literal, block-scoped function declaration, class, computed property, const declaration, default parameter, destructuring, extended object literal, for-of loop, generator, let declaration, member declaration, new.target, octal literal, RegExp flag 'u', RegExp flag 'y', rest parameter, spread expression, super, template literal, exponent operator (**), async function, trailing comma in param list, object literals with spread, object pattern rest]