Preparing for Install

Installing Liferay DXP is easy. But before you begin, you should answer a few questions.

• Which version of Liferay will you install?
• On which application server will you install Liferay DXP?
• Can you install a Liferay DXP bundle or do you need to install Liferay DXP on an existing application server?
• Which database will you use with Liferay DXP?
• How do you plan to store your data?
• Can your network support Liferay DXP?

Next, you’ll answer these questions and learn the basic steps for installing Liferay DXP.

Obtaining Liferay DXP

Anyone can download Liferay DXP from liferay.com. Click Product → Downloads, and you’ll be able to download either the open source version of Liferay DXP or a trial of the commercial version in several different formats. These include our convenient bundles as well as .war files for installing Liferay DXP on your application server of choice.

Liferay enterprise subscribers can download Liferay DXP from the Help Center.

So what is a Liferay DXP bundle anyway? A Liferay DXP bundle is an application server with Liferay DXP pre-installed. Bundles after Liferay DXP 7.1 GA1 and Liferay Portal CE 7.1 GA1 are released in 7-Zip (.7z) and gzipped tar (.tar.gz) compressed file archive formats. Bundles are the easiest way to install Liferay DXP. Liferay DXP is bundled with a number of application servers; choose the one that best fits your needs. If you don’t currently have an application server preference, consider starting with the Tomcat bundle. Tomcat is one of the most lightweight and straightforward bundles to configure. If you have an open source application server preference, choose the server you prefer from the available Liferay DXP bundles. Liferay DXP requires a Java JDK 8 or 11.

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

Please note that Liferay DXP is not able to provide application server bundles for proprietary application servers such as WebLogic or WebSphere, because the licenses for these servers don’t allow for redistribution. Liferay DXP’s commercial offering, however, runs just as well on these application servers as it does on the others. You must follow our manual installation procedure using a .war file to install Liferay DXP on proprietary application servers.

Once you have Liferay DXP, you can plan out your installation. First, prepare your database. Second, install Liferay DXP. Third, configure your network. Fourth, configure search. You can install Liferay DXP either by using a bundle or by installing it manually on your existing application server. Next, we’ll go over the steps it takes to install Liferay DXP.

Liferay DXP Installation Steps

Before you begin installing Liferay DXP, you should review these basic installation steps:

1. Choose a database server to use with Liferay DXP and create a new database. Determine whether you want Liferay DXP to manage your database connection or your application server to manage your database connection. We recommend that you let Liferay DXP manage your database connection. Liferay DXP can connect with several open source or enterprise level document repositories.

2. Gather mail credentials for sending email notifications to users. Determine whether you want Liferay DXP to manage your mail session or your application server to manage your mail session. Liferay DXP provides a built-in mail session but also supports a JNDI mail session. We recommend that you let Liferay DXP manage your mail session.

3. Install either a Liferay DXP bundle or install Liferay DXP on an existing application server (further instructions below).

4. Choose IPv4 or IPv6. Determine which address format is best for your network (further instructions below).

5. Determine how you’ll configure Elasticsearch. Liferay DXP’s default embedded configuration is not supported for production use, so you must install Elasticsearch separately, either on the same infrastructure or on its own.

6. Configure ports (optional). Liferay’s application server (e.g., Tomcat or Wildfly) uses certain ports for purposes like handling incoming HTTP requests, HTTPS requests, or AJP requests, etc. If you start your application server in debug mode, there’s a port listening for a debugger to connect. If desired, you can configure these ports. Please refer to your application server’s documentation for information on its default ports and how to configure them.

   Liferay also provides access to its OSGi framework through a configurable port:

   module.framework.properties.osgi.console=localhost:11311

   You can override this default property by copying the line above to your LIFERAY_HOME/portal-ext.properties file and adjusting the port number.

We’ll go through the steps in order, so first we’ll look at the Liferay DXP database.

Step 1: Choose a Database Server and Create a New Database

The recommended way of setting up your Liferay DXP database is also the simplest. Liferay DXP takes care of just about everything. You only need to take two simple steps:

1. Create a blank database encoded with the character set UTF-8. Liferay DXP is a multilingual application and needs UTF-8 encoding to display all of its supported character sets.

   Note: If you plan to migrate from one database vendor to another, configure the database to use the default query result order you expect for entities Liferay DXP lists.

   Note: If you use Sybase, configure the database to allow null values by default.

2. Create a database user for accessing this database. Grant this database user all rights, including the rights to create and drop tables, to the blank Liferay DXP database.

   Important: Liferay requires reading from and writing to the database. The Liferay database user must therefore have permissions to read and write data.

Liferay DXP uses this database user’s credentials to connect to the Liferay DXP database either directly or through its application server. During its initial startup, Liferay DXP creates the tables it needs in the database you just created. It does this automatically, complete with indexes.

This is the recommended way to set up Liferay DXP. It enables Liferay DXP to maintain its database automatically during upgrades or when various Liferay DXP plugins that create database tables of their own are installed. This method is by far the best way to set up your Liferay DXP database.

Warning: If you’re using an Oracle database, use the ojdbc8.jar driver library with at least Oracle 12.2.0.1.0 JDBC 4.2 versioning because data truncation issues have been detected reading data from CLOB columns.

If you choose to set up Liferay DXP’s database with the recommended permissions described in this section, you can skip to the next section.

Warning: The instructions below are not ideal for Liferay DXP installations. This procedure is documented here so that enterprises with more restrictive standards can install Liferay DXP with stricter (but sub-optimal) database settings. If it’s at all possible, we recommend that you use the method described in the previous section instead of the procedure outlined below.

Even though Liferay DXP can create its database automatically, some enterprises prefer not to allow the database user configured in an application server to have the database permissions necessary for Liferay DXP and its plugins to maintain their tables. For these organizations, Select, Insert, Update and Delete are the only allowed permissions. Thus, in this section we explain how to set up the database manually. If your organization is willing to grant the Liferay DXP database user the permissions to create and drop tables in the database–and this is the recommended configuration–then simply use the recommended configuration described in the previous section.

1. Create a new, blank, database for Liferay DXP.

2. Grant full rights to do anything to the Liferay DXP database to the Liferay DXP database user.

3. Install Liferay DXP and start it so that it automatically populates its database.

4. Once the database has been populated with the Liferay DXP tables, remove the permissions for creating and dropping tables from the Liferay DXP database user.

There are some caveats to running Liferay DXP like this. Many Liferay DXP plugins create new tables when they’re deployed. Additionally, Liferay DXP has an automatic database upgrade function that runs when Liferay DXP is upgraded. If the Liferay DXP database user doesn’t have enough rights to create/modify/drop tables in the database, you must grant those rights to the ID before you deploy one of these plugins or start upgrading Liferay DXP. Once the tables are created or the upgrade is complete, you can remove those rights until the next deploy or upgrade. Additionally, your own developers might create plugins that need to create their own tables. These are just like Liferay DXP’s plugins that do the same thing, and they cannot be installed if Liferay DXP can’t create database tables. If you wish to install these plugins, you will need to grant rights to create tables in the database each time before you attempt to install them.

Liferay DXP offers several configurations to store Documents and Media files by setting the dl.store.impl= property. Available options are Simple File System Store, Advanced File System Store, CMIS Store, DBStore, JCRStore, and Amazon S3Store. In addition, Liferay DXP can be connected to various open source and enterprise-level document repositories. All of the repositories are connected to Liferay DXP through hooks available on Liferay Marketplace (see below).

Once you have your database and document repository ready, you can install Liferay DXP on your server.

Step 2: Gather Your Mail Credentials

Liferay DXP uses a mail server to send email notifications. As part of the install, therefore, you will need to have credentials that Liferay DXP can use to connect to your mail server. Specifically, you’ll need to have the following information:

• Incoming POP Server and port
• POP User Name
• POP Password
• Outgoing SMTP Server and port
• SMTP User Name
• SMTP Password
• A list of JavaMail properties that would override a default configuration

Once you’ve gathered this information, you’re ready to move on to the next step.

Step 3: Install

The next step is to install Liferay DXP. You can do this in one of two ways: by installing Liferay DXP bundled with an application server, or by installing Liferay DXP manually on an existing application server. Each Liferay DXP installation’s Liferay Home contains several folders.

By far the easiest way to get Liferay DXP installed is to use a bundle. Though bundles are pre-packaged for demo purposes, it is very easy to turn them into full, production-ready Liferay DXP instances.

Step 4: Network Configuration

Liferay DXP supports both IPv4 and IPv6 address formats. You must choose between IPv4 or IPv6. By default, Liferay DXP uses IPv4 addresses. If you are using IPv6, you will have to configure Liferay DXP. There are two simple steps.

1. In the application server’s environment settings, set -Djava.net.preferIPv4Stack=false.

2. Create a portal-ext.properties file in your portal’s Liferay Home folder (if one does not already exist) and set the tunnel.servlet.hosts.allowed property to the target hosts you want to allow (e.g., 0:0:0:0:0:0:0:1).

Step 5: Configure Elasticsearch

Liferay DXP by default ships with an embedded version of Elasticsearch. While this configuration works well for demo purposes, it is not supported in a production installation. After you install Liferay DXP, you’ll need to configure it to connect to a standalone Elasticsearch server or cluster. Depending on the size of your installation, this standalone instance of Elasticsearch can reside either on the same machine you have Liferay DXP on or a different machine. For performance purposes, it is better to install Elasticsearch on a separate machine.

Step 6: Liferay Marketplace and Portal Security

The Liferay Marketplace is an integral part of the Liferay DXP experience. The Marketplace plugin is required to be installed on Liferay DXP. The Marketplace plugin enables a host of features that extend beyond just access to the online Liferay Marketplace. Some of the key features the Marketplace plugin enables are

• Liferay Marketplace: direct access to our online Marketplace
• App Manager: ability to install, uninstall, and update apps
• Bundled Apps: easily manage apps that may come bundled with your Liferay DXP
• Developer Apps: ability to manage apps that you’re developing
• License Manager: streamlined license management for your Liferay DXP and apps

The portal installation process deploys and registers the Marketplace plugin automatically. If you’re installing Liferay DXP in an environment that would prevent this from happening, you’ll have to perform one of several workarounds.

Now that you know where you’re headed, you can install Liferay DXP. If you have decided to install Liferay DXP using a bundle, continue with the next section. If you’re installing Liferay DXP manually, skip to the section for your application server of choice. Once you have Liferay DXP installed manually or via a bundle, you can move on to using Liferay DXP’s Setup Wizard, configuring mail, and installing Elasticsearch.