The easiest way to install Liferay DXP is to use a Liferay DXP bundle. However, this is not always possible. Some organizations have an existing infrastructure into which Liferay DXP must be installed. Other organizations have standardized on a particular application server. Liferay DXP has been designed to work well with many leading application servers. Even if you have to manually install Liferay DXP on an existing application server, the procedure is straightforward. Before you get started, note that there are two distinct approaches to managing Liferay DXP’s data source and mail session. Let’s review these options.
Liferay DXP provides two ways to configure your data source:
- Use Liferay DXP’s built-in data source
- Use your application’s server’s JNDI data source
Liferay DXP recommends that you use the built-in data source. Liferay DXP’s data source
is configured by a number of properties that are set in a properties file. By
default, you can enter database connection information on the Basic
Configuration page that appears when Liferay DXP starts for the first time. The
setup wizard stores the information you entered in a configuration file called
portal-setup-wizard.properties in your Liferay Home folder. Liferay DXP’s
built-in data source uses this information to connect to the database.
Although Liferay DXP recommends that you use the built-in data source, that’s not the only option. Some organizations prefer to use the data source provided by their application server of choice. In this case, a JNDI lookup provides a handle to the data source and the application server manages the connection pools. So you can configure Liferay DXP to use your application server’s data source, if that’s desired.
To do this, you’ll need to create your own configuration file and skip the setup wizard. Since you’d be creating this file after the wizard anyway, this isn’t such a big deal. We show you how to configure a JNDI data source in the Manual Configuration section below.
Since mail sessions are configured similarly to data sources, we’ll look at them next.
As with databases, you have two ways to configure your mail server:
- Use Liferay DXP’s built-in mail session
- Use your application server’s mail session
Liferay DXP recommends using the built-in mail session. After you’ve started
Liferay DXP, you can configure a mail server through Liferay DXP’s Control Panel.
Liferay DXP’s default configuration looks for a mail server on the same machine on
which Liferay DXP is running and it tries to send mail via SMTP to this server. If
this is not your configuration, you’ll need to modify Liferay DXP’s defaults. To do
this, you can use a
portal-ext.properties file in your Liferay Home folder
To use your application server’s mail session, you must create it in your
application server. It should point to your mail server. Once you’ve created a
mail session in your application server, you’re ready to point Liferay DXP to it.
You can do this through your
portal-ext.properties file or through
Liferay DXP’s Control Panel.
You now have all the background information you need to decide whether to use Liferay DXP’s built-in data source or the one provided by your application server. Similarly, you can now decide whether to use Liferay DXP’s mail session or your application server’s mail session. If you’re planning to use Liferay DXP to manage both your database connection and mail session, great! When you start Liferay DXP, simply enter your database connection information on the Basic Configuration page and then enter your mail server information through the Control Panel.
If you’re planning to let your application server manage your database connection, you can’t use Liferay DXP’s setup wizard. If you want to configure your application server to manage either your database or mail server, you’ll have to follow the instructions in the Manual Configuration section below. The Liferay DXP Installation documentation for each specific application server also includes instructions for configuring your application server to manage Liferay DXP’s database connection and mail server.
If you want your application server to manage either your database connection
or mail server (or both), you’ll need to manually create this configuration.
Create a text file called
portal-ext.properties in your Liferay Home folder.
This file overrides default properties that come with Liferay DXP. The first
setting you’ll override is the default configuration that points Liferay DXP to the
embedded HSQL database.
As stated above, there are two ways to set up the connection:
- Use Liferay DXP’s built-in data source
- Use your application server’s data source
Use the setup wizard if you’re using Liferay DXP’s data source. If you want to use your application server’s pool, continue with this procedure.
If you want to use your application server’s data source, you will have to
create a connection pool in your application server that points to your
database. The connection pool should be called
jdbc/LiferayPool. You can find
instructions for how to do this in the installation documentation for each
application server that Liferay DXP supports. To tell Liferay DXP to use your
jdbc/LiferayPool connection pool, add the following directive to your
Next, install Liferay DXP according to the instructions for your application server. Once it’s installed, you can set up the mail configuration.
For mail, you should use Liferay DXP’s Control Panel to create the configuration.
Go to Control Panel → Server Administration → Mail and enter your
settings for your mail session settings. If, however, you’re setting up a lot
of Liferay DXP machines and they’re all going to have similar mail configurations,
it’s easier to do the configuration once and then copy the configuration file
to multiple machines. In this case, you’ll want to use the
portal-ext.properties file. To use the built-in mail session, use the
following properties and customize their values for your environment:
To use your application server’s mail session, create it first. Then specify it
When you’ve finished, save the file.
All the instructions above assumed that you wanted to install Liferay DXP at the root context of your server. But what if that isn’t the case? Next, you’ll see how to use a different context for Liferay DXP.
By default, Liferay DXP is configured to sit at the root (i.e.,
/) of your
application server. Dedicating your application server to running only Liferay DXP
is a good practice. This allows your portal environment to be separated
from your web application environment. This is generally a best practice for
portals which, by definition, are application development platforms in and of
themselves. For this reason, your Liferay DXP instance is likely to be hosting many
applications and even integrating several of them together on a single page.
For this reason, you should design your system so your portal environment has
all the resources it needs to do this. Configuring it so it is the sole
consumer of any other
.war files that get deployed to the application server
helps to make sure your system performs optimally.
If, however, you want Liferay DXP to share space on an application server with other applications, you can. In this instance, you might not want to make Liferay DXP the default application in the root context of the server. If you want to install Liferay DXP in a context other than the root context, follow the instructions from your app server vendor. No additional steps are necessary.