Liferay portal instances are a way through which Liferay handles data separation. Each Liferay instance can be seen as a separate website within the same server. Each instance has its own domain name (setup via the Virtual Host attribute of the instance). Each portal instance is only accessible through this domain name and not otherwise.
How to setup Liferay portal instances?
To setup a new Liferay portal instance you have to be logged in as an admin. Then go to the Control Panel via Manage > Control Panel and then in the Server section click on Portal Instances > Add. You have to key in the following information:
- WebID – this is an identifier for the portal instance; it will appear in the breadcrumbs and just as a remark, this will be validated as an URL (don’t know why) so the same rules as for an URL will apply (no spaces, no funky characters, etc)
- Virtual Host – the domain name associated with the portal instance (eg. www.ba-pro.com). All requests made on this domain will be funneled to the instance in question. All requests to domains that resolve through the DNS to the server, but are not associated to a portal instance will be funneled to the default instance;
- Mail domain – this domain refers to the domain name auto completed in the Username field of the log in screen. It does not have any other actual impact since the users can have any email as username;
- Shard name – name of the associated shard; if you don’t know what they are, you can read more about Liferay shards (Liferay sharding paragraph). Basically Liferay shards are logical or physical database areas which hold data for a specific instance. Setting up Liferay with shards requires some configuration in the portal-ext.properties file (view the official documentation for setting up shards), and as I found out the hard way, if you want physical separation for the shards (so each instance on its own database) then you also need to make some adjustments in the Spring configuration of Liferay – if you are interested you can read more about configuring Liferay with shards. Depending on how the server is configured, shards can be assigned to portal instances manually or through a round-robin algorithm.
- Max users – as an admin of the entire portal it might be useful to limit the number of users for a certain instance; here’s where you can do it; 0 allows an unlimited number of users.
What is the difference between a portal instance and a portal shard?
A portal shard is an area of the database (logically or physically separated) prepared to receive data for a portal instance. So, before creating an instance you need to have a shard prepared. Once the instance is created, it will reside in the portal shard.
You can setup the server such that the Liferay portal instances reside in the same database or in different databases.
How do Liferay portal instances work?
Liferay portal instances are very useful if you want to host multiple websites on the same Liferay installation. But, how do they actually work?
The Liferay portal implements an HTTP filter (com.liferay.portal.servlet.filters.virtualhost.VirtualHostFilter), which is among the first executed filters. This filter looks at the domain for which the request was made and identifies the portal instance by comparing it to the Virtual Host attribute.
Digging deep in the liferay architecture, in the persistence layer service namely, you can find that Liferay portal instances are called companies (Company object is stored in the company_ table in the database of the default instance). Probably the name company comes from an earlier version and was kept as such. The database ID of the Company object is very important as whenever a service or persistence layer method is invoked the companyId parameter is passed to indicate from which instance (shard) the data should be retrieved.
Liferay uses AOP (aspect oriented programming) which allows cutting in just before execution of certain methods. So, when certain methods from the service or persistence layers is invoked a class (com.liferay.portal.dao.shard.ShardAdvice) will intervene and select the instance (shard) on which to do the work. This is done by the code looking into the parameters for the companyId parameter. The ShardAdvice class is configured in portal-impl/src/META-INF/shard-data-source-spring.xml in the aop:aspect node. There you will find the matching rules applied to method execution and which code gets called from the ShardAdvice class to handle the calls.
Liferay portal instances pros and cons
Pros
You get data separation for websites stored in Liferay. There is no danger of data cross over (theoretically).
You can limit the number of users per website/instance/shard.
Portal management becomes easier.
Allows better backup and restore procedures (theoretically). In practice this is possible when you separate the shards each in its own database.
Cons
Setting up Liferay portal instances requires a bit of extra configuration than the regular installation.
Once created, a portal instance will occupy it’s shard and cannot be easily removed. It can however be deactivated.
This setup takes up more resources.
Data migration on one single instance is a pain.
