Configuring Remote Staging in a Clustered Environment

If you’re running Liferay DXP as a clustered environment and you want to use remote staging, you must configure it properly for a seamless experience. In this tutorial, you’ll learn how to set up remote staging in an example clustered environment scenario. The example environment assumes you have

• A Staging instance with database configurations and a file repository different from the cluster nodes
• A balancer responsible for managing the traffic flow between the cluster’s nodes
• Two nodes that call two Liferay app servers (e.g., App Server 1 and App Server 2), both of which are connected to the same database

Figure 1: This is the assumed setup for your clustered environment.

The steps below also assume your web tier, application tier, and cluster environment are already configured. You may need to adjust the configurations in this tutorial to work with your specific configuration.

Let’s begin!

1. You must secure the communication made between your nodes and Staging server. Add the following property to both app servers’ and Staging server’s portal-ext.properties file:

   tunneling.servlet.shared.secret=[secret]
   

   This secret key denies other portals access to your configured portal servers. If you’d like to set your secret key using hexadecimal encoding, also set the following property in your portal-ext.properties files:

   tunneling.servlet.shared.secret.hex=true
   

   Note: The following key lengths are supported by the available encryption algorithms:

   • AES: 128, 192, and 256-bit keys
   • Blowfish: 32-448 bit keys
   • DESede (Triple DES): 56, 112, or 168 bit keys (Liferay places an artificial limit on the minimum key length and does not support the 56-bit key length)

   For example, you can use OpenSSL to generate a 128-bit AES key:

   openssl enc -aes-128-cbc -k abc123 -P -md sha1
   

2. You must allow the connection between the configured IPs of your app servers and the Staging server. Open both of your app servers’ portal-ext.properties files and add the following properties:

   tunnel.servlet.hosts.allowed=127.0.0.1,SERVER_IP,[STAGING_IP]
   tunnel.servlet.https.required=false
   

   The [STAGING_IP] variable must be replaced by the staging server’s IP addresses. The SERVER_IP constant can remain set for this property; it’s automatically replaced by the Liferay server’s IP addresses.

3. If you’re validating IPv6 addresses, you must configure the app server’s JVM to not force the usage of IPv4 addresses. For example, if you’re using Tomcat, add the following attribute in the $TOMCAT_HOME\bin\setenv.[bat|sh] file.

   -Djava.net.preferIPv4Stack=false

4. Restart both app servers for the new properties to take effect.

5. Configure the TunnelAuthVerifier property for your nodes’ app servers. There are two ways to do this:

   • Use a .config file (recommended): In the $LIFERAY_HOME/osgi/configs folder of one of your node Liferay DXP instances, create (if necessary) a com.liferay.portal.security.auth.verifier.tunnel.module.configuration.TunnelAuthVerifierConfiguration-default.config file and insert the properties listed below. Creating one .config file configures all cluster nodes the same way. For more information on .config files, see the Understanding System Configuration Files article.

       enabled=true
       hostsAllowed=127.0.0.1,SERVER_IP,STAGING_IP
       serviceAccessPolicyName=SYSTEM_USER_PASSWORD
       urlsIncludes=/api/liferay/do
     

   • Via System Settings: Navigate to the Control Panel → Configuration → System Settings → Foundation → Tunnel Auth Verifiers. Click on the /api/liferay/do configuration entry and add the Staging IP address to the Hosts allowed field. If you choose to configure the TunnelAuthVerifier this way, you must do this for all nodes (e.g., App Server 1 and App Server 2).

6. On your Staging instance, navigate to the Site Administration portion of the Product Menu and select Publishing → Staging. Then select Remote Live.

   

   Figure 2: When selecting the Remote Staging radio button, you're given a list of options to configure.

7. For the Remote Host/IP field, insert the balancer’s IP of your web tier. Configuring the Staging instance with the balancer’s IP ensures the availability of the environment at the time of publication from staging to live.

8. Enter the port on which the balancer is running into the Remote Port field.

9. Insert the remote site ID of your app servers into the Remote Site ID field. The site ID of all your app servers are the same since they are configured for the same database and are shared between nodes.

   Navigate to the Site Administration portion of the Product Menu and select Site Settings to find the site ID.

10. Save the Remote Live settings.

That’s it! You’ve configured remote staging in your clustered environment.