Staging Best Practices for DXP

This article documents some recommended suggestions that administrators should be mindful of when they prepare to use Staging on their Sites, or when they are managing their already existing Staging infrastructure.

Resolution

When planning to use Staging, one of the first decisions that needs to be made is whether to enable Local Live or Remote Live Staging.

In order to help you make this decision, please consider the following information:

Local Staging vs. Remote Staging

Local Staging:

Both your Staging Site and your Live Site are hosted on the same server. When enabled, the Liferay platform creates an identical hidden Site within the portal by publishing the pages and the selected portlet data. The cloned Site becomes the Staging environment and the original Site becomes the Live environment.
Local Live staging allows you to publish Site changes quicker because there is no network traffic involved. However, your server needs to have more resources, since the staged content is stored in the same database as the production content.
If your Site already has a lot of data when you enable Local Staging, creating a clone of it can take a while, and it can be a resource intensive operation. Your data is also not as well backed up as with Remote Live Staging.

Remote Staging:

Your Live Site is located on an entirely different Liferay instance/server. When enabled, the Liferay platform establishes a connection between the two Sites over the network. The Site on the remote server becomes the Live environment, and the current Site becomes the Staging environment.
With Remote Live Staging the data is more separated, so it is easier to distinguish and manage your assets. It also lets you deploy new versions of apps and content to your Staging environment without worrying about interfering with your Live environment, since they are located on a different server. However, publishing is slower with Remote Live than with Local Live since data needs to be transferred over a network.
Of course, you also need more hardware to run a separate staging server.

Optimize Your Hardware

You should think about your hardware before you start using Staging.

Network Speed:

In a Remote Staging environment the network will be a serious factor that you should consider. If you are planning to publish huge amount of data, lots of images, big videos, you should be aware that it needs to be pushed through the network. Because of this, placing the remote server outside of your subnetwork may affect the publication speed negatively.

Document Read/Write Speed:

For example if you use lots of images, you should make sure that Liferay can read and write them in a very fast way. This is true for your local filesystem as well, but especially for external repositories where you access your documents remotely.

CPU Speed:

In case you are publishing huge amounts of Web Content, it is not a disk or network intensive operation, but you need to make sure that your CPU is up for the task, because in this use case the Articles' actual string data will be processed and updated on the fly. For example all the links and references to their embedded data will need to be changed according to their location on the Live environment.

In order to come up with the hardware and Staging configuration that best fits your needs, it is highly recommended to do a lot of testing with different scenarios.

Decide Which Portlets You Want to Stage Before Turning on Staging

When you enable Staging, you need to select what content types you would like to stage. Since turning Staging on and off for individual portlet data could cause data inconsistencies between the Staging and the Live Site, it is not possible to modify the individual portlet configuration once you enable Staging.

In case you need adjustments later on, you will need to turn off Staging altogether and re-enable it with your new configuration, which can cause additional issues if your Site already contain lots of data.

Publish Early, Publish Often, Publish Small

Local Staging creates a clone of your Site right away when you enable it and Remote Staging uses the network to publish your data. Both cases can be a time and resource consuming operation. Because of this, regardless of the type of Staging you use, it is recommended to enable Staging on newly created, clean Sites.

A very common mistake is when someone creates all the content first, and only turns on Staging as the last step.

If you turn Staging on in a very early phase of the Site creation process, you can have smaller publications, you can publish incremental data, you don't need to wait for a long time for a publication to finish, and you can uncover possible issues early on.
You can publish smaller amounts of data by restricting your data set. You can do this based on content type and date range. For example, it is possible to publish only the recently created Web Content Articles without their version history (if you only need the latest version) or their referenced content (if you already published those separately, you don't need to do it again).

Create a Plan for Maintaining Database-File System Consistency

In the case of a staging failure, a transactional database will be able to revert back to its original state. However, the file system (if it is not “database-stored” like DBStore) is not transactional and therefore will need be rolled back. This could potentially cause a discrepancy between a file and where it is being referenced from.

Because of this, administrators should take great care if they decide to stage the document library, making sure that regular backups of both their database and their file system are being maintained. Administrators should also ensure that it is clear which file system backups will correspond with particular database backups.

Use the Same Patch Level

If you are moving data between two different environments using export/import or Remote Staging, you need to make sure that the same patches are applied to all servers being used. LAR files exported from an older patch version should still be successfully imported into all future releases of the same Liferay version, but it is still highly recommended to update these export files regularly. This is also true if you are importing a LAR file which originated from the same server.

It is essential that all servers are updated with the same patch level which ensures that the code base of the export and import processes are in sync and they will handle the data in the same way.

How to Debug Staging

The majority of Staging issues happen during data validation because of the inconsistencies the process finds. Because of this, the most important step during troubleshooting is to locate the problematic entries. There are some general ways that you can use to do this:

Break the publication into components.
Try to publish your Web Content Articles only. Then Documents and Media only, etc. Until you have isolated the issue.
Increase the log level of Staging related classes to DEBUG in order to get more information from the stacktrace. This way you can see which entry was processed before the issue happened.
Go to Control Panel > Server Administration > Log Levels and set the following Categories to DEBUG:

com.liferay.exportimport

com.liferay.exportimport.lifecycle

com.liferay.exportimport.lar

You can configure the Liferay platform to keep the generated LAR file in the temp folder of the Live environment's Application Server after a successful or failed Staging publication. This can be very useful if you want to analyze exactly what data was processed by the Liferay platform. To do this, you can set the following properties in your portal-ext.properties file:

    #

    # Set this property to false to avoid deleting the temporary LAR during a

    # a failed staging publication process.

    #

    staging.delete.temp.lar.on.failure=false

    
    #

    # Set this property to false to avoid deleting the temporary LAR during a

    # a successful staging publication process.

    #

    staging.delete.temp.lar.on.success=false

How to Turn Off Staging Properly

Depending whether you use Local or Remote Live Staging, you will need to be aware of a couple of things if you are ever planning to eventually disable Staging on your Site:

In case of Local Staging:

When you enable Local Staging, a duplicate Site is created to hold all Staging content. This means that the original "real" Site is the Live one, which will only contain the created data if you publish it from Staging. Because of this, when Staging is disabled, all content that was not published will be lost. Keep in mind that draft content types are not published, so they can be lost too.

In case of Remote Staging:

Only the connection between the Live Site and the Staging Site is removed. This means no data is deleted when Staging is disabled.
Since special restrictions are applied to the Remote Live Site when you enable it, these restrictions need to be revoked when Staging is disabled.
Because of this, when Staging is disabled, the Staging server will need to communicate with the Live server through the network to revoke these restrictions. If the Live server is not accessible (removed, or has different address), you will not be able to disable Staging normally, only with the “forcibly disable staging” option. With this option, the Staged Site’s Staging information will be cleared (not the content), but the Live Site will remain in a locked state.