Submit Feedback
Legacy Knowledge Base
Published Sep. 10, 2025

Virtual Host Quick Guide

Written By

Justin Choi

How To articles are not official guidelines or officially supported documentation. They are community-contributed content and may not always reflect the latest updates to Liferay DXP. We welcome your feedback to improve How To articles!

While we make every effort to ensure this Knowledge Base is accurate, it may not always reflect the most recent updates or official guidelines.We appreciate your understanding and encourage you to reach out with any feedback or concerns.

Legacy Article

You are viewing an article from our legacy "FastTrack" publication program, made available for informational purposes. Articles in this program were published without a requirement for independent editing or verification and are provided"as is" without guarantee.

Before using any information from this article, independently verify its suitability for your situation and project.

The official Apache Virtual Host Documentation states: 

The term Virtual Host refers to the practice of running more than one web site (such as company1.example.com and company2.example.com) on a single machine. Virtual hosts can be "IP-based", meaning that you have a different IP address for every web site, or "name-based", meaning that you have multiple names running on each IP address. The fact that they are running on the same physical server is not apparent to the end user. (See: Apache Virtual Host Documentation)

So why use a virtual host? One possible use case is to have two different access points to access the same database. The Liferay platform implements name-based virtual hosts at two different levels: (1) through the Virtual Instance settings (formerly Portal Instances for those upgrading from legacy Portal) and (2) at the site level.

Users can create a new Virtual Instance so that they can have a different site domain while running on the same Liferay platform installation. Furthermore, Liferay platform sites can have their own public and private virtual hosts that maps to the site's public and private page sets. Please note that a virtual instance can contain several sites.

Resolution

To enable different virtual host domain names to be recognized by the Liferay platform, these names have to resolve to the Liferay server hosting those domains. This usually involves some work in the DNS servers so that these names can be associated to the corresponding IP address, but that specific exemplar lies out of scope of this article. 

To add a new Virtual Instance:

  1. Start Liferay DXP
  2. Go to Control Panel > Configuration > Virtual Instances
  3. Click the Add button at the bottom right.
  4. There are four fields and a toggle box:
    • Web ID: A general convention is to use the domain name for this; it is a user-generated ID for the instance.
    • Virtual Host: Put the domain name you configured in the network here. When users are directed to your Liferay server via this domain name, the Liferay platform will then be able to send them to the proper virtual instance.
    • Mail Domain: Enter the domain name for the mail host for this instance. The Liferay platform will use this to send email notifications from the instance.
    • Max Users: Enter the maximum numbers of user accounts for the virtual instance to support. The default '0' means an infinite number, not zero.
    • Active: Use this toggle to choose whether to create an active or an inactive virtual instance.
  5. Click the Save button.

In addition, users can designate each site within Liferay DXP to have its own virtual host name. Thus, it is possible to define one virtual host for the public pages and another one for the private pages in the same site. To do so: 

  1. Go to the Control Panel > Sites
  2. Select the site to be configured. Click Configuration > Site Settings
  3. Scroll down to the Site URL drop down.
  4. Follow the helpful prompts to designate virtual host names and friendly URL for the site: 
    01.png
  5. Click the Save button.

As shown in step 4, sites can have a friendly URL. In addition, public and private virtual host names can be configured. This creates an additional mechanism to access site pages. 

In order to access a page, the Liferay platform needs to define 4 data items:

  • the virtual instance,
  • the site,
  • whether the page is public or private, and,
  • the page itself.

These data items are obtained from the URL.

Let's assume /home is a public page in the guest site which was created in the default virtual instance. By default, the Liferay platform will serve that page when receives the following URL:

http://localhost:8080/web/guest/home

Where:

  • localhost is the portal instance virtual host name. Please note the Liferay platform creates a default virtual instance and sets its hostname to localhost
  • web is a predefined prefix that denotes we are accessing public pages. The prefix group can be used to access private pages.
  • guest denotes the site friendly URL. Note the Liferay platform creates a default site in the default virtual instance and sets its friendly URL to /guest
  • home is the page friendly URL in that site. Note the Liferay platform creates a page in the default site and sets its friendly URL to /home

Enabling site-level virtual host names just adds an additional way to extract the data from the URL. Let's assume that the name site-virtual-host is set as the public virtual host for the site. Then, the Liferay platform can receive the following URL:

http://site-virtual-host:8080/home

Where:

  • site-virtual-host is the site-level virtual host defined for the public pages of the site. This tells the platform 3 things: the site, the virtual instance and the fact that the URL points to a public page
  • home is the page friendly URL in that site.

To sum up, pages can be accessed through the domain name of the virtual instance containing the site, and using the site's virtual host in case it's defined.

Frequently Asked Questions (FAQs)

  1. Can I use the same virtual host name multiple times?
    No. Virtual host names are unique across all portal instances; that is, across a full Liferay DXP installation. Virtual hosts names have to be unique or otherwise, the portal will enter an infinite loop when deciding who this request is for. Please note that both the instance-level and the site-level domain names are stored in the VirtualHost table; as a result, a site virtual host cannot reuse another site's virtual host name even if both sites belong to different virtual instances. As further proof of the uniqueness of virtual hosts names, admins can look in the database tables where the VirtualHost table uses the hostname column as primary key. 
  2. If a site's virtual host names are unique, is that the only access point?
    No. Let's assume that a site's public pages have a distinct virtual host name (e.g. iheartbiscuits.com); users can still access those pages from the Portal Instance's own virtual host name (e.g. iluvcookies.com).
  3. Is this functionality available in legacy Liferay versions?
    Yes. Virtual Instances in Liferay DXP used to be called portal instances in Liferay Portal. Site-level virtual hosts (name remains unchanged) are found in legacy Liferay Portal versions. 

Additional Information

Did this article resolve your issue ?
Legacy Knowledge Base
Did this article resolve your issue ?