Mastering multisite solutions with Liferay: lessons learned

What we build

The first solution was a true multisite project—one of the largest we’ve ever built. By the end, we had 307 unique websites in 55 languages. The goal was to create a digital platform where people worldwide could learn about our client’s work in innovation, sustainability, and culture. Each country had its own site, featuring both an English version and localized content managed by regional editors. While all sites followed a unified design, they required enough flexibility to meet the needs of each market.

The second solution was a whitelabel platform, allowing our client’s partners to launch their own branded websites within the same infrastructure. While our client already used Liferay for their main website, they needed a way to offer secure, maintainable sites to partners—each with its own domain and branding. We started with just a couple of sites but designed the system to scale efficiently while maintaining central control and local flexibility.

The challenges we faced

Building and maintaining hundreds of websites brings unique challenges:

• Site Management & Maintenance: How do you efficiently manage such a vast number of sites and keep both code and content up to date and centralized?
• Rapid Deployment: How can you quickly set up new sites without introducing manual bottlenecks?
• Customization Without Complexity: How do you give editors the flexibility they need while maintaining brand consistency and avoiding an unmanageable amount of custom code?
• Editor Engagement & Training: How do you onboard and support editors across so many different teams and languages?

We tackled these challenges head-on and learned five key lessons that can help anyone working with Liferay multisite solutions.

Lesson 1: Measure twice, code once

In other words, make sure your solution actually fits the requirements.  A well-planned solution is the foundation of a successful project. Before writing a single line of code, ask yourself:

• How many sites will there be? This impacts the hosting infrastructure and setup process.
• How much will design and content vary? This determines your need for theming, page templates, master pages, or Liferay Stylebooks.
• How are sites and content related? This affects whether you should use asset libraries, shared content, or a combination of global and site-specific elements.
• What roles and permissions are required? The degree of editorial freedom dictates your permissions model and how you structure page-building tools.

We tested our approach with a proof of concept (PoC) before scaling up. For example, we experimented with site templates but found that certain templates didn’t propagate updates as expected. By validating our choices early, we prevented costly redesigns later.

Additionally, we tapped into the Liferay Slack community for insights from other developers. Learning from others' experiences helped us make more informed architectural decisions.

Lesson 2: There are many roads to Rome—but some are less bumpy

Choosing the right multisite deployment strategy is very important because you want to set up sites quickly and efficiently and keep your code maintainable in one place. Choosing the right multisite deployment strategy is like navigating a city. Some roads are fast but rigid (highways), while others offer flexibility at the cost of complexity (winding backroads). And then you can even pave your own road, fully customized to meet your needs, but you’ll have to be prepared to do some serious groundwork. With Liferay, you have multiple deployment options, each with its own strengths and trade-offs:

Lesson 2:  Site Templates – Fast and simple, but limited

Site templates are a low-code, easy-to-use approach for creating new sites with pre-configured pages, structures, and fragments. They allow for rapid deployment and previewing changes before rolling them out.

Pros:

• Quick to set up, making it ideal for smaller projects.
• No development effort required.
• Allows for a consistent layout across multiple sites.

Cons:

• Limited propagation support—changes made to the template do not automatically update existing sites.
• Can become difficult to maintain at scale.
• Not as flexible as other options.

Lesson 2: Site Initializers – Structured and automated

• Liferay supports OSGi-based site initializers and Client Extensions-based initializers, which allow developers to preconfigure sites with specific content, templates, and permissions.

Pros:

• Fully automated, requiring no manual setup after deployment.
• Recommended best practice by Liferay.
• Updates can be controlled through versioned deployments.

Cons:

• Requires more upfront development.
• No UI support for previewing contents before deployment.
• Some entities (like fragments) are duplicated when global scope is not supported.

Lesson 2:  Custom Site Initializers – Maximum control, but higher maintenance

For highly specific requirements, you can build a custom site initializer that goes beyond Liferay’s default capabilities. These can support more advanced propagation strategies, such as updating templates across multiple sites.

Pros:

• Offers the highest level of control over site structure and content.
• Can include features like site cloning and partial updates.
• Ideal for enterprises with complex multi-brand architectures.

Cons:

• Requires ongoing maintenance and updates.
• Needs custom development to ensure smooth functionality.
• More complex deployments, especially for cloud-based environments.

Steps to create a custom Site initializer

1. Add siteInitializer
   1. Have a class implementing service = SiteInitializer to register the site initializer
2. Create importer
   1. Custom service that is based on BundleSiteInitializer
   2. Save siteInitializerKey in site type settings to update later
3. Add resources
   1. Add resources folder with correct folder structure
   2. Base structure on example
   3. Add placeholder tokens for ids that are dynamic
4. Add Gogocommand
   1. Implement service = GogoCommand commands to update sites and/or global
   2. Retrieve sites based on siteInitializerKey

The right choice of multisite deployment strategoy depends on your project’s balance between speed, maintainability, and flexibility. 

Lesson 3: If it ain’t broke, don’t fix It—And if it is, tell Liferay support

Custom development is tempting, but sticking to Liferay’s out-of-the-box features minimizes technical debt and maintenance overhead. We developed the acronym REBEL to remind ourselves of best practices. It is ironic, because key is not to REBEL against Liferay, but to work with it.

• Rethink your approach: Use low-code solutions when possible. Leverage headless API and React instead of Freemarker and Service Locator. Use low-code objects instead of Service Builder.
• Embrace out-of-the-box functionality: If Liferay already provides a feature, use it!
• Be critical about user requirements: It’s crucial to explain to stakeholders or your product owner that meeting certain demands might come with a heavy cost to maintainability or even just with a heavy cost versus value delivered. In the end it is about cost and value for the customer. We’ve actually demonstrated that staying close to Liferay standards allows us to deliver faster and more robust solutions.
• Extend, don’t override: When custom development is unavoidable, take a modular approach. Always extend onto Liferay instead of overriding. This keeps as much compatibility with Liferay updates as possible.
• Learn and stay up to date: New features are being added to Liferay all the time. Keep track of new Liferay features to avoid redundant development. For example, we nearly built a custom cookie banner before realizing that Liferay was rolling out an official solution in the next update. A little patience saved us a lot of effort.

Lesson one to three were about the technical foundations of a stable solution, lesson four and five will be all about keeping the people who use it happy. And that brings us to our fourth lesson:

Lesson 4: Variety is the spice of branding

A good multisite solution must balance flexibility, usability, and branding. Editors need enough control to tailor their sites to local needs, but too much freedom can lead to inconsistent branding and frustrated designers.

Our approach:

• Set clear expectations: Work closely with clients to define the right balance between flexibility and control. This also depends on their tech-savyness and needs. 
• Use structured content and fragments: Instead of advanced styling options, we designed flexible but user-friendly fragments that act as configurable building blocks. For example, we don't create small micro fragments that users have to drag and drop into eachother to make a full row of items. We define our fragments as rows , so users don't have to worry about mobile responsiveness. Also, we add user friendly configurations .
  • DO NOT -> Create a free format text input fields where users have to add classes to style a fragment. DO -> create a dropdown with style variations with clear names. 
  • DO NOT-> Create an image, text and container fragment to allow variations like image left and text right and have editors drag and drop it themselves DO -> Create a fragment "Image and text" that is automatically responsive and can be configured to show the image left or right.
• Provide editor-friendly tools: Make the editing experience intuitive so users don’t seek alternative solutions. Just implementing the design is not enough, always have requirements to make editors works easy and intuitive. Even if the customer does not ask for it, it is your responsibility to make Liferay as user friendly as possible. 

Lesson 5: Keep your end-users close and your trainers closer

A perfect solution means nothing if users don’t know how to use it. To drive adoption, we focused on early engagement and ongoing training:

• Early content migration: Editors started working on content halfway through the build to gain a sense of ownership.
• Regular editor standups: Twice-weekly meetings, led by a non-developer team member, created a space for feedback and iteration. These standups weren’t just meetings; they became moments of discovery and collaboration, where even small piece of feedback turned into significant improvements.
• Train-the-trainers model: To reach the localized editors,  we implemented a “train the trainers” model, where we trained the centralized team who then trained and supported the local editors. They also user their knowledge to  develop e-learning materials.. This way, localized editors received training that was relevant and easy to understand.
• E-learning resources: We developed structured training materials to support editors as they onboarded.

This layered approach increased adoption rates and ensured that users felt confident working with the platform.

Wrapping Up: Your Roadmap to Multisite Success

To wrap it all up, our journey through building successful multisite solutions can be summed up in five key lessons. Think of these as your roadmap, guiding you past potential roadblocks and onto a smoother path to success.

1. First, investigate your requirements and test Liferay’s capabilities. It’s like scouting your route before a road trip—know where the sharp turns and detours are, so you’re not caught off guard.
2. Second, choose the right deployment strategy. This is your choice between highways and backroads—some are fast but rigid, others flexible but take longer to navigate. Pick wisely, and your journey will be much smoother.
3. Third, stick to Liferay standards. Imagine these as the guardrails that keep you safe. Veer too far off course, and you’ll end up in a world of pain trying to maintain your solution.
4. Fourth, balance flexibility, usability, and branding. Think of this as preparing your copilots for when it’s their turn to take the wheel. Give your editors the right tools and a clear understanding of the journey, so when they start driving, they’ll keep things smooth and enjoyable for everyone
5. Finally, engage and empower your end-users. Keep them close, because their feedback and training are your keys to lasting success. They’re eventually the drivers who need to feel confident behind the wheel of your solution. 

By following these principles, you can build scalable, maintainable multisite solutions that truly meet the needs of your users. We hope our insights help you navigate your own Liferay multisite projects with fewer bumps along the way!  

Originally Presented at Liferay DevCon 2024

The insights shared in this blog come from my talk at Liferay DevCon 2024, where I had the opportunity to share d these insights with fellow developers. If you’d like to see the full presentation, including additional details and real-world examples, you can watch the talk online.