Free trial

Liferay multi-tenant topology using Portal Instances with Amazon S3

Liferay supports multi-tenant configurations via multiple portal instances in a single web container. What is the Portal instance? It is a Liferay’s feature which allows you to have two or more separated user spaces under one physical installation. It simplifies the deployment and administration. Liferay also provides a Properties Override capability to override default properties file so each Portal Instance can have it’s own properties file. As you might know, settings for Documents and Media are put in properties file.

In this article we will look at options to setup multi-tenant deployment (using Portal Instances) for document management system with repository at Amazon S3 and try to describe use cases that will consider ability to setup:

  1. different types of storage repository per Portal instance
  2. same type of storage and shared repository, but with different object space (buckets) for each Portal instance
  3. shared repository and shared object space (bucket) across all Portal instances

Note: object space in Amazon S3 storage is called bucket.

Use cases

Different types of storage repository per tenant

Suppose you are an owner of a server machine and have many customers (for simplicity imagine 2 customers) of different size, each one wants enterprise solution based on Liferay Portal. Liferay supports many storage repositories and suppose that there could be an automatic process that sets up Portal Instance for first customer (small type up to 10 users) to use file system storage for document management and Second Portal instance for second customer (mid size with 10-1000 users) with Amazon S3 as a storage repository. Is it possible to setup Liferay to use different types of repositories for each tenant (Portal instance)?

Shared repository with different object space (buckets) per tenant

As in previous situation, you have 2 customers. Both of them wants to use Liferay with Amazon S3 but both want to have their own object space (bucket)  in order to keep data separated from other tenants. Can Liferay be configured for it’s Portal instances to use different object spaces (buckets) under same Amazon S3 repository?

Shared repository and shared object space (bucket) for multiple tenants

Imagine one customer with separated Portal instances per it’s various departments in this situation. Each department stores it’s documents and media in S3 storage in common place for the company so customer chooses to use same storage – Amazon S3 and same object space (bucket), where all documents and media will be separated by directory tree.

Demonstrated functionality

We have performed some of the tests to demonstrate above use cases. But first, please see some technical background on how you setup Portal instances, how each instance is configured and what was our test environment we have used.

To setup multi-tenant environment we have:

  1. Created Portal Instances per each tenant – Liferay allows to create multiple Portal Instances within single Liferay server deployment (see Portal Instances at Liferay User Guide). You can create Portal instance as a Liferay Administrator via Control Panel. Please note:
    1. Liferay User Guide for Portal Instances states: “Data for each portal instance are kept separate from every other portal instance. All portal data, however, is kept in the same database.
    2. Deleting instances can be done only by changing or deleting keys in Liferay’s database. However, Liferay’s developers are working on it. Please follow this issue. If you need to change Web-ID right now, please follow the discussion on Liferay’s forum.
  2. Created own settings for each Portal instance – once Portal instances are created specific properties can be loaded per instance in following way:
    1. Create or edit (at the same place as If you don’t know where, visit our previous article and continue to section “Set up Liferay with Amazon S3 without data migration”) and add one line:
    2. Next step is to edit or create and add following line:
      • this tells to Liferay to look for property file for specific instance. You can change this pattern as you need.
    3. Create Portal instance’s own property file. If you use the same line as mentioned before, the name has to be in format:

      (e.g.: for Web ID = “” create file “”, for Web ID = “Instance 1” create file “portal-Instance”.)

  3. Prepared test environment – we have used Liferay Portal Community Edition 6.1.1 CE GA2 bundled with Tomcat 7.0.27 and configured it with two instances with following Web-IDs:
    • instance1
    • instance2

To make sure that instance’s property file has been successfully loaded look for messages in application server log:

Loading file: .../webapps/ROOT/WEB-INF/classes/
                                      for {companyId=10900, webId=instance1}
Loading file: .../webapps/ROOT/WEB-INF/classes/
                                      for {companyId=10900, webId=instance1}
Loading file: .../webapps/ROOT/WEB-INF/classes/
                                      for {companyId=10613, webId=instance}
Loading file: .../webapps/ROOT/WEB-INF/classes/
                                      for {companyId=10613, webId=instance2}

Output shows that each Portal instance property file has been loaded. We have also configured Liferay to use Amazon S3 as a storage repository. This setup vary among use cases and it’s capabilities are demonstrated below.

Use case demonstration

Let’s get back to our use cases. Below we are presenting short description of the setup and attaching Test results from which you can see how system behaves in various scenarios:

First scenario – two Portal instances setup with different storage types (local file system and Amazon S3)

Each tenant wants to use different type of storage for it’s documents and media:

Customer Storage type Bucket name
Tenant 1 Amazon S3 CUSA
Tenant 2 Local file system

To achieve this we have tried to setup properties for connection to Amazon S3 storage in Portal instance 1 property file

We have also configured include-and-override=portal-${easyconf:webId}.properties property in the file. See content of,, files for details.

Test results for multi-tenant functionality using Portal instances with different storage types, local file system and Amazon S3:

  • First two tests (TR_LR-S3_001 and TR_LR-S3_002) show results for described setup, while tests TR_LR-S3_011 and TR_LR-S3_012 show results when Tenant 1 uses local file system and Tenant 2 Amazon S3.


Findings: From above scenario it seems that unless settings for connection to Amazon S3 are specified in the and regardless of using include-and-override property, local file system storage is used for all Portal instances.

Second scenario – usage of shared Amazon S3 account across tenants with separate object space (buckets)

Liferay is configured in this scenario in a way for each tenant to be connected to the same Amazon S3 repository but it’s document library to be separated in independent/dedicated object spaces – separate Amazon S3 buckets.

Customer Storage type Bucket name
Customer 1 Amazon S3 CUSB1
Customer 2 Amazon S3 CUSB2

Settings for connectivity to Amazon S3 are provided within in this situation. Separate Bucket names are  set in each Portal instance property files. See content of,, files for details.

Test results for multi-tenant functionality using Portal instances connected to the same Amazon S3 storage but using different object space (bucket) for each Portal instance:

  • Scenarios TR_LR-S3_021 –  TR_LR-S3_032 show configuration of both instances to separate buckets
  • Scenarios TR_LR-S3_041 – TR_LR-S3_092 show some of the negative test cases when incorrect or empty bucket name is provided


Findings: From above scenario and test cases we have executed it seems that bucket name is taken from property file that was loaded as last one and not from property file dedicated for given instance.  As per Liferay engineering the feature of overriding per instance is legacy so settings for different portal instances should be done via Control Panel only and hence it is at present limitation on portal side. You can follow explanation in following issue LPS-38021 about why properties for connection to S3 cannot be overridden for different instances via

A possible solution/workaround to achieve this setup is to programatically customize Liferay’s as explained in the issue.

Third scenario – usage of shared Amazon S3 account across tenants with same/shared object space (bucket)

Liferay is configured in this scenario in a way for each tenant to be connected to the same Amazon S3 repository and using same storage – bucket to store files.

Customer Storage type Bucket name
Customer 1 Amazon S3 CUS
Customer 2 Amazon S3 CUS

We have added S3 connection settings along with target bucket name right into in this use case. We have not used portal instance property files as it is not necessary.

Test results for multi-tenant functionality using Portal instances connected to the same Amazon S3 storage and using same object space (bucket) for each Portal instance:

  • Scenarios TR_LR-S3_0101 and  TR_LR-S3_0102 show upload of images from both Portal instances to same bucket – object space


Findings: From above scenario you can configure multiple portal instances to same bucket with settings connection to Amazon S3 in the Uploaded files are being handled properly, but the storage is shared and uploaded files of first tenant can be potentially accessed by other tenants or it’s administrators.


What we have tried in this article is usage of different types of storage and usage of shared or different buckets under shared Amazon S3 account. All tests have been done in multi-tenant topology using Portal Instances feature. Liferay correctly finds and reads instance properties files, as can be seen from our test results. We have observed during our testing, that using different storage types per portal instances seems not supported, as both tenants use local file storage as default. Use of two or more buckets simultaneously by different portal instances also does not seem to be supported as demonstrated in second scenario. Hence, as per our findings, when trying to achieve multi-tenant topology using Portal instances against Amazon S3, only configuration to be working for us out-of-the-box, is to use same Amazon S3 storage with same bucket – object space, to which documents and files will be uploaded for each tenant / Portal instance. Third scenario is default way described in Liferay User guide.

It seems that setup of  Documents and Media library to different repository type for different Portal instances isn’t supported yet and therefore, we suggest you to consider saving your repository connection settings right in the, rather than in instance properties file. We already informed Liferay developers with this use case via feature request LPS-37245.

If you need to provide different types of storage or different buckets in Amazon S3, look for multiple Liferay installation deployments each deployed on it’s web container using either independent CMS database (or pointed to shared CMS database) with specific configuration for Documents and Media repository for each installation.

Used resources

Portal Instances section and Properties Override section in Liferay’s user guide

amazon liferay portal

One Response to “Liferay multi-tenant topology using Portal Instances with Amazon S3”

  1. Liferay EPCM Solutions says:

    Thank you for sharing!Nice post.

Leave a Reply

Related articles


Let’s make LLMs generate JSON!

In this article, we are going to talk about three tools that can, at least in theory, force any local LLM to produce structured output: LM Format Enforcer, Outlines, and Guidance. After a short description of each tool, we will evaluate their performance on a few test cases ranging from book recommendations to extracting information from HTML. And the best for the end, we will show you how forcing LLMs to produce a structured output can be used to solve a very common problem in many businesses: extracting structured records from free-form text.

Notiondipity: What I learned about browser extension development

Me and many of my colleagues at profiq use Notion for note-taking and work organization. Our workspaces contain a lot of knowledge about our work, plans, or the articles or books we read. At some point, a thought came to my mind: couldn’t we use all this knowledge to come up with project ideas suited to our skills and interests?

From ChatGPT to Smart Agents: The Next Frontier in App Integration

It has been over a year since OpenAI introduced ChatGPT and brought the power of AI and large language models (LLMs) to the average consumer. But we could argue that introducing APIs for seamlessly integrating large language models into apps developed by companies and independent hackers all over the world can be the true game changer in the long term. Developers are having heated discussions about how we can utilize this technology to develop truly useful apps that provide real value instead of just copying what OpenAI does. We want to contribute to this discussion by showing you how we think about developing autonomous agents at profiq. But first a bit of background.