Understanding Portal Properties

portal.properties is Liferay's master configuration file. It controls nearly every aspect of the portal: search engine integration, email settings, caching behavior, security policies, feature toggles, web content behavior, and much more. When you upgrade Liferay, properties change — some disappear (deprecated), some are new (features), and some change their default values.

Why This Matters for Upgrades

Liferay upgrades are complex. One common pitfall is carrying forward old portal-ext.properties settings to the new version without checking if they still exist or if their values have changed. This can cause:

• Silent failures: Old property names are ignored, new defaults take over (unexpected behavior).
• Broken features: Deprecated properties no longer work; you need their replacements.
• Performance issues: Cache or search settings changed; your old values no longer apply.
• Security gaps: New security properties exist; you miss them if you don't upgrade your config.

How to Use This Diff Tool

1. Pick your versions: Select your current Liferay version and the one you're upgrading to (e.g., 7.3 → 7.4).
2. Review the diff: The tool shows three categories:
   • Added: New properties in the target version — features you might want to configure.
   • Changed: Properties that exist in both but with different default values — check if your overrides still make sense.
   • Removed: Deprecated properties — remove them from your portal-ext.properties file.
3. Filter by category: Focus on what matters to you (Search, Mail, Security, etc.) instead of scrolling through hundreds of properties.
4. Check your config: Open your portal-ext.properties file and look for any properties that the diff tool marked as removed or significantly changed.
5. Update cautiously: Only add new properties if you understand what they do. Leave defaults alone unless you have a reason to customize.

Property Categories

Properties are organized by function:

Before and After Upgrade Checklist

Before Upgrade

• Backup your current portal-ext.properties file
• Use this tool to see what changed in your target version
• Review removed properties — remove them from your config
• Check changed properties — validate your overrides still apply
• Document why you customized each property

After Upgrade

• Merge your customizations into the new portal-ext.properties carefully
• Remove deprecated properties
• Test thoroughly in a staging environment
• Monitor logs for unrecognized property warnings

Common Properties That Change

These properties frequently change across versions and warrant your attention:

• search.engine.vendor — Changes between Elasticsearch versions; breaking if misconfigured.
• dl.store.impl — Switches between database and file system storage; affects document library performance.
• oauth.token.expires.in — Security setting; was added in 7.1, doesn't exist in 7.0.
• feature.flag.* — New features locked behind flags; enable/disable as needed.
• journal.article.version.compare — Controls web content versioning behavior.

Frequently Asked Questions

What are portal.properties?

portal.properties is Liferay's main configuration file. It contains hundreds of settings that control portal behavior — search engine, mail, caching, security, feature flags, etc. Most are optional with sensible defaults.

Why does this matter during upgrades?

Properties change between versions — some are deprecated, some are new, some change default values. If you don't update your portal-ext.properties, you might use old settings or miss new features. This tool shows exactly what changed.

What properties should I actually review?

Focus on the ones that affect your customizations: search config, mail settings, cache behavior, permissions, scheduler, web content, asset settings. Leave system properties alone unless you know what you're doing.

Should I add all new properties to my portal-ext.properties?

No. Only add properties you need to customize. Liferay provides sensible defaults for most properties. Adding unnecessary entries makes upgrading harder and configuration management messier.

Where do I get my current portal.properties?

Check your $LIFERAY_HOME/portal-ext.properties file (your custom overrides). Compare it with the official portal.properties in your Liferay installation or GitHub to see what's deprecated or new.

Official Resources

• Liferay Upgrade Basics (Liferay Learn)
• Recommendations for portal-ext.properties (Liferay Dev)
• Portal Properties Reference (Liferay Learn)