To take full advantage of Liferay Connected Services (LCS), you must first register your server with LCS. Before doing so, however, there are a few things you must take care of. The sections in this guide walk you through these steps:
- Downloading the LCS Client App
- Preconfiguring LCS to Connect Through a Proxy
- Ensuring Access to LCS
- NTP Server Synchronization
- Configuring the Patching Tool
- Installing the LCS Client App
Also, the last section in this guide shows you how to upgrade the LCS client app once your server is connected to LCS. We highly recommend that you upgrade the app whenever Liferay releases a new version of it.
First, you’ll download the LCS client app.
To connect to LCS, you must first purchase and download the latest version of the LCS client app for Liferay Portal 6.2 EE. You can do this via Liferay Marketplace.
Use these steps to purchase and download the app (if you’ve already purchased the app, you can skip to step 3 to download it):
Navigate to the LCS client app in Liferay Marketplace. Sign in to Marketplace, then click the the LCS client app’s Free button.
Select the project you want to associate the app with, accept the license agreement, and then click the Purchase button. Marketplace then displays your receipt.
On the receipt, click See Purchased. This takes you to the page where you can download the LCS client app. To download the app, click the App button next to the version of the app you want to download.
Great! You’ve successfully downloaded the LCS client app. Before installing it, however, there are a few additional preconfiguration steps you should complete. The following sections of this guide walk you through these, and then show you how to install the app.
If your server connects to the Internet through a proxy, you must set some properties in either your server or the LCS client app before deploying the app. There are therefore two ways to set these properties, depending on whether you set them in your server or the LCS client app:
As JVM app server arguments. Set these properties to the appropriate values for your proxy:
-Dhttp.proxyHost= -Dhttp.proxyPort= -Dhttp.proxyUser= -Dhttp.proxyPassword= -Dhttps.proxyHost= -Dhttps.proxyPort=
Note that the user, password, and https properties are only needed if your proxy requires authentication.
To set the properties inside the LCS client app’s WAR file, you must first extract it from the app’s LPKG file (the app downloads from Liferay Marketplace as an LPKG file). Expand the LPKG file, then locate and expand the client’s WAR file:
You must set the properties in the WAR’s
portlet-ext.propertiesfile. Follow these steps to do so:
a. In the LCS client’s WAR file, create the file
WEB-INF/classes/portlet-ext.properties(or open this file if it already exists).
b. Add the following properties at the end of
portlet-ext.propertiesand set them to the appropriate values for your proxy:
If your proxy requires authentication, you should also add the following properties and set them to the appropriate values for your proxy:
If your proxy requires NTLM authentication, you must also add the following properties:
proxy.auth.type=ntlm proxy.domain= proxy.workstation=
Be sure to set
proxy.workstationto the appropriate values for your proxy. Note that you can leave
proxy.workstationblank if you don’t need it.
c. Repackage the LCS client WAR with the modified
portlet-ext.propertiesfile, then repackage the LPKG file with the LCS client WAR. Make sure the repackaged LPKG file has the same name as the original LPKG file downloaded from Liferay Marketplace.
Next, you’ll learn how to ensure that the LCS client can access LCS.
For the LCS client app to work, it must be able to access the following DNS names. If your server is behind a proxy and/or a firewall, then you must open access to these:
As an added security measure, you can also restrict traffic to HTTPS.
The next section discusses NTP server synchronization.
For LCS to work properly, the application server running Liferay Portal should be synchronized with a time server. If it’s not, you may get log errors similar to these:
ERROR [pool-6-thread-3][HandshakeTask:68] java.lang.RuntimeException: Handshake expired. Check that the server is synchronized with an NTP server. WARN [liferay/hot_deploy-1][LCSHotDeployMessageListener:186] LCS portlet is not connected java.lang.RuntimeException: com.liferay.jsonwebserviceclient.JSONWebServiceInvocationException: com.fasterxml.jackson.core.JsonParseException: Unrecognized token 'oauth_problem': was expecting ('true', 'false' or 'null')_ at [Source: oauth_problem=timestamp_refused&oauth_acceptable_timestamps=1477311475-1477312075; line: 1, column: 14] [Sanitized]
For information on how to synchronize your application server with a time server, see your application server’s documentation.
Next, you’ll learn how to configure Liferay Portal’s patching tool.
LCS uses Liferay Portal’s patching tool to apply updates. In Liferay Portal 6.2 EE bundles, the patching tool is pre-installed. If you’re not running a bundle, you must download and install the patching tool separately.
Once installed, there are a few steps you must complete before LCS can use the
patching tool. Note that the commands below apply to Linux, Unix, and Mac. If
you’re running Windows, drop the
.sh from each command that has it.
Navigate to the
patching-tooldirectory on the command line. It’s typically located in the Liferay Home folder. Liferay Home is usually the parent folder of the application server’s folder.
To let the patching tool discover your Liferay Portal installation, run this command:
To configure the patching tool, run this command:
On server startup, the patching tool agent installs the patches downloaded by LCS. For the agent to start with your server, you must set the
javaagentproperty in the JVM options to point to your patching tool installation’s
patching-tool-agent.jar. Be sure to specify the correct path to this file:
If your patching tool is installed in a location other than the Liferay Home folder, you must also specify the
patching-toolfolder’s path as an app server JVM argument. Do this with the
There are also a few other things to consider when using the agent. Due to class
loading issues, the agent starts in a separate JVM. You can specify options for
it by using the
-Dpatching.tool.agent.jvm.opts="-Xmx1024m -Xms512m -Dfile.encoding=UTF-8"
You may also experience issues on Windows if the user starting the app server doesn’t have administrator privileges. Here are some examples of the errors you may see:
java.nio.file.FileSystemException: ..\webapps\ROOT\WEB-INF\lib\util-java.jar: Not a file! java.io.FileNotFoundException: java.io.IOException: Access refused
To solve this, set the
java.io.tmpdir system property as follows in the
-Dpatching.tool.agent.jvm.opts="-Xmx1024m -Xms512m -Dfile.encoding=UTF-8 -Djava.io.tmpdir=%TMP%"
The agent also has some flags you can set to control how it behaves:
debug: Provides verbose output in the console.
nohalt: Starts the portal even if the agent encounters an issue.
You can specify these as follows:
Once you’ve addressed the above preconfiguration steps, you’re ready to install the LCS client app. Follow these steps to install the app:
Shut down your Liferay Portal instance if it’s running.
Place the LCS client app in the
[Liferay_Home]/deployfolder (create this
deployfolder if it doesn’t exist). Note that the Liferay Home folder is usually the parent folder of the application server’s folder.
Great! Now you’re all set to connect your Liferay Portal instance with LCS. For instructions on this, click here to proceed to the next article.
The next section shows you how to upgrade the LCS client app. We highly recommend that you do this whenever Liferay releases a new version of the app.
Your server should always be running the latest version of the LCS client app. There are two ways to upgrade the app, depending on the exact LCS preconfiguration steps you followed:
Via Liferay Marketplace inside your running Liferay Portal instance. Use this method if you don’t need to configure the LCS client app (e.g., to connect through a proxy) before it deploys.
To perform the upgrade, first navigate to Admin → Control Panel → Apps → Purchased. Apps needing an update are listed first. Click Update next to the LCS client app. Note that you may need to restart your server for the upgrade to complete.
Manually, after downloading the LCS client app’s LPKG file to your machine. Use this method if you need to preconfigure the LCS client app to connect through a proxy.
To update the LCS client app manually, follow the previous sections in this guide for downloading and preconfiguring the app. Then deploy it to
[Liferay Home]/deployas you would any other app.
Contact Liferay Support if you need additional assistance with the upgrade process.