Adding a Virtual Instance

Before you do anything in Liferay DXP to add a virtual instance, you must configure its domain name in your network to point to your installed Liferay DXP system.

Important

As of Liferay DXP 2026.Q1, using multiple domains requires a Liferay DXP Enterprise Subscription. A domain may have unlimited sub-domains.

Once the domain name is ready, create the virtual instance:

1. Go to Global Menu () → Control Panel → Virtual Instances.

2. Click New () to open the Add Instance form.

   With database partitioning enabled, New opens a menu instead, so click New → Add.

3. Complete the Add Instance form. See Add Instance Fields for each field.

4. Click Add.

   Liferay then checks the Web ID, Virtual Host, Mail Domain, and Max Users fields. When default.admin.password is blank, it also checks the admin user’s Screen Name, Email Address, and Password. If any field values are invalid, an error appears in the form. Otherwise, the form closes and instance creation runs in the background (Liferay DXP 2026.Q4+). See Asynchronous Virtual Instance Operations for how instance creation runs in the background and how to create instances with POST /portal-instances/batch.

In Liferay DXP 2026.Q4+, Liferay notifies you when creation finishes. If creation fails, the notification gives the reason. If creation succeeds, reload the Virtual Instances page to see the new instance.

Important

The notification can arrive shortly before the new instance finishes initializing. If the instance’s site doesn’t load yet, wait a moment and try again.

With database partitioning enabled, you can also create an instance by importing a database partition exported from another installation. See Migrating Liferay Instances.

Add Instance Fields

Web ID: Specify the instance ID. Using the domain name is a common convention.

Virtual Host: Set the domain name you configured in your network. When people use the domain name, they are directed automatically to this instance.

Mail Domain: Enter the mail host’s domain name for the virtual instance. Email notifications are sent from the instance using this domain.

Max Users: Set the maximum number of user accounts the virtual instance supports. Enter 0 to support unlimited users.

Active: Set the virtual instance to active or inactive. Inactive virtual instances aren’t accessible to anyone, even the administrator.

Virtual Instance Initializer: Choose the Site Initializer to use on the virtual instance. See Site Initializers for more information.

By setting default.admin.password to a blank value in your portal properties, you get more options when adding virtual instances. Use these to configure the admin user that’s automatically created on new instances.

Screen Name: Set the screen name for the admin user.

Email Address: Set the email address for the admin user.

Password: Set the account password for the admin user.

First Name: Set the first name for the admin user. The default value is “Test”.

Last Name: Set the last name for the admin user. The default value is “Test”.

Creating Virtual Instances with Configuration Files

You can set the default values for new virtual instances and their automatic admin users with a configuration file. In your Liferay Home, create a .config file named com.liferay.portal.instances.internal.configuration.PortalInstancesConfiguration~[virtualHostName].config. Replace [virtualHostName] with the name of the virtual host (e.g. com.liferay.portal.instances.internal.configuration.PortalInstancesConfiguration~www.able.com.config). You can set these properties (some are available only in newer Liferay versions):

active=B"true"
maxUsers=I"0"
mx="www.able.com"
siteInitializerKey=""
virtualHostname="www.able.com"
addDefaultAdminUser=B"true"
adminPassword="secretPassword" (Liferay DXP 2024.Q4+/Portal GA129+)
adminScreenName="Test Admin" (Liferay DXP 2024.Q4+/Portal GA129+)
adminEmailAddress="[e-mail]" (Liferay DXP 2024.Q4+/Portal GA129+)
adminFirstName="Test" (Liferay DXP 2024.Q4+/Portal GA129+)
adminMiddleName="" (Liferay DXP 2024.Q4+/Portal GA129+)
adminLastName="Test" (Liferay DXP 2024.Q4+/Portal GA129+)

Now you can navigate to the instance using its domain name. You’re brought to what looks like a clean install of Liferay DXP. This is your new virtual instance! You can configure it any way you like.