Migrating Configurations and Properties
Your current DXP installation’s OSGi configurations (7.0+) and properties (such as portal properties and system properties) set up your DXP instance to fit your needs. To use these settings in your new DXP instance, you must migrate them to your new Liferay Home and update them.
Overview
Migrating Liferay Home and Application Server Files
-
Merge the Liferay Home files and application server files that you have added and edited from your backup to your installation. The files may include but are not limited to these:
/license/*
: Activation keys. (Subscription)/log/*
: Log files./osgi/configs/*.config
: OSGi configuration files. Only copy over your custom configuration files. Do not include any*-default.config
files generated by Liferay.portal-*.properties
: Portal properties files, such asportal-ext.properties
.- Application server files: Modified scripts and configuration files.
web.xml
: Portal web application descriptor.
-
Replace the new installation’s
[Liferay Home]/data
folder with the[Liferay Home]/data
folder from your backup. -
Set up the File Store (Document Library) by copying it from your backup to the new installation and or configuring the new installation to use it via a
.config
file.
Updating Settings For the Database Upgrade
Upgrade processes in DXP and in some Marketplace apps use portal properties and OSGi configurations. Upgrade processes in your custom code may also require property updates and configuration updates. These settings and updates must be in place before the database upgrade. Other updates can be done after the database upgrade.
Here are the settings updates DXP upgrade processes require:
- Database driver
- Document library store implementation name (See Updating the File Store)
Check your Marketplace apps and custom code for settings updates they require.
Database Drivers
Check your database vendor documentation for the recommended database driver. If a new driver is recommended, replace the existing driver JAR file and update the jdbc.default.driverClassName
property in your portal-ext.properties
file with the new driver class name.
MySQL example:
jdbc.default.driverClassName=com.mysql.cj.jdbc.Driver
See the Database Templates for more driver examples.
Migrating Portal Properties
If you’ve overridden the locales
Portal Property, override it in the new installation before upgrading. This assures upgrading data for all of your locales.
The properties discussed here can be updated after database upgrade. Migrating properties involves these actions:
- Updating your
liferay.home
property, if you changed it - Using Blade CLI to report property changes
- Converting properties to OSGi configurations
- Special property migration considerations
Using Blade CLI to Report Incompatible Properties
The Blade CLI tool’s upgradeProps
command reports changes between portal properties files. The tool reports these types of changes.
- Properties that cause exceptions, if not updated.
- Properties moved to a module
portal.properties
file. - Properties moved to OSGi configuration.
- Properties not found in the new DXP version.
In many cases, the upgradeProps
command explains the required update or references more information on the property change.
The blade upgradeProps
command format:
blade upgradeProps -p {old_liferay_home_path}/portal-ext.properties -d {new_liferay_home_path}
Here is example output from running the blade upgradeProps
command:
...
index.search.query.suggestion.dictionary
MODULARIZE AS OSGI - This property matches with the following OSGI config, select the most appropriate:
- searchQueryResultWindowLimit from com.liferay.portal.search.configuration.DefaultSearchResultPermissionFilterConfiguration
index.search.spell.checker.dictionary
KEEP - This property is still present in the new portal.properties.
sites.friendly.url.page.not.found
KEEP - This property is still present in the new portal.properties.
web.server.protocol
KEEP - This property is still present in the new portal.properties.
...
Converting Properties to OSGi Configurations
Properties in modularized features have changed and are now deployed in OSGi configuration files (OSGi Config Admin).
For example, in 6.2, the Simple File Store used this portal property to specify the store root directory:
dl.store.file.system.root.dir=${liferay.home}/data/document_library
Now the store is configured in a .config
file called com.liferay.portal.store.file.system.configuration.FileSystemStoreConfiguration.config
that specifies the root directory with a setting like this:
rootDir="{document_library_path}"
Put the .config
files in a folder called [Liferay Home]/osgi/configs
.
The Control Panel’s System Settings screens (under Configuration) manage the OSGi Config Admin values. These screens are the most accurate way to create .config
files. Find the screen that configures the feature you want to configure, click Save, and then use the options button to export the screen’s configuration to a .config
file.
Special Property Migration Considerations
There are resources for migrating properties related to specific environments, Liferay versions, and features. They’re called out here for convenience.
-
Updates to file store settings are discussed in Updating the File Store.
-
If you’re on Liferay Portal 6.1 or earlier, adapt your properties to the new defaults that Liferay Portal 6.2 introduced.
-
If you have a sharded environment, configure your upgrade to generate a non-sharded environment.
-
Examine the default portal property changes in 7.4, 7.3, and 7.2.
-
Liferay’s image sprite framework is deprecated as of 7.2 and is disabled by default. The framework requires scanning plugins for image sprites. If you don’t use the framework, there’s no need for it to scan for images sprites. If you use the framework yourself, enable it by overriding the default
sprite.enabled
portal property (since 7.2) value with the following setting in yourportal-ext.properties
file.sprite.enabled=true
NoteYou can build image sprites using any framework you like and deploy them in your plugins.
Next Steps
Your Liferay settings are ready to use in your new DXP instance. Next, update the file store.