Skip to content

Primary domain

Multiple domains can point to a VIP platform environment, but only one domain can be the primary domain. This is true for WordPress single site environments, WordPress multisite environments, and Node.js environments.


To view, assign, or update an environment’s primary domain in the VIP Dashboard, a user must have at minimum an Org member role or an App write role for that application.

Assign a primary domain

All VIP Platform environments are initially created with a convenience domain assigned to them. Convenience domains are intended for temporary use by production environments during development and preparation for launch. 

  • On a non-production environment the convenience domain can be optionally replaced by a custom primary domain.
  • On a production environment the convenience domain must be replaced with a custom primary domain in order for a site(s) on that environment to be launched and accessible to public traffic.

When a primary domain is assigned to an environment, all instances of the convenience domain in the site’s database tables are replaced by the primary domain.


A custom domain that does not yet have DNS pointed to VIP can be assigned as the primary domain. Until DNS for the domain is pointed to VIP, the site will only be accessible by modifying the local machine’s hosts file.

After the domain switch, it may take up to 10 minutes for a site to receive traffic.

WordPress single site environments

Before completing the steps below, the new custom domain must already be added to the environment’s VIP Dashboard.

  1. Navigate to the VIP Dashboard for an application.
  2. Select an environment from the environment dropdown located at the upper left of the VIP Dashboard.
  3. Select “Domains & TLS” from the sidebar navigation at the left of the screen.
  4. Locate the new domain from the list of the environment’s domains.
  5. Select the “•••” button located to the right of the domain.
  6. Select “Make Primary Domain” from the overflow menu.

All instances of the previous domain in the site’s database tables will be replaced with the new primary domain.

Update a primary domain

Until a WordPress single site environment has been launched, the primary domain can be changed any number of times within the Domains & TLS panel of the VIP Dashboard.

Once the environment is in a “Launched” state, request assistance from VIP Support to update the primary domain to a different custom domain.

WordPress multisite environments

For WordPress multisite environments, the primary domain can be assigned or updated by using the launch tooling in the Network Sites panel of the VIP Dashboard. The custom domain that is assigned to the main site (ID 1) is the primary domain for the environment.

In the Network Sites panel:

  • For an unlaunched production WordPress multisite environment, assign a primary domain by selecting the button labeled “Launch this site” for the main site (ID 1). Follow the steps in the launch tooling to update the main site’s domain and mark the site status as “Launched”.
  • For a launched production WordPress multisite environment, the primary domain can be updated by selecting “Update domain” for the main site (ID 1). Follow the steps in the launch tooling to assign or update the site’s domain and mark the site status as “Launched”.
  • For a non-production WordPress multisite environment, assign or update the primary domain by selecting “Update domain” for the main site (ID 1). Follow the steps in the launch tooling to assign or update the site’s domain and mark the site status as “Unlaunched”.

Identify a primary domain

If a primary domain is already assigned to an environment, it can be identified in the VIP Dashboard or with VIP-CLI.


VIP Dashboard

All custom domains that are mapped to an environment are listed in the Domains & TLS panel of the VIP Dashboard for that environment. An environment’s primary domain is indicated by a label with the text “Primary” to the right of a listed domain.


A user can list an application’s environments and a limited set of their setting values, including the primary domain, with the vip app [ID] command.

As an example, environment details for an application with the name example-app can be retrieved by running the command vip app example-app. The example command output below reports that the application’s production environment is in a launched state with the primary domain

$ vip app example-app
+ id: 8886
+ name: example-app
+ repo: wpcomvip/my-org-example-app
│ id   │ app id │ name       │ type       │ branch     │ current commit │ primary domain                 │ launched │
│ 8886 │ 8886   │ production │ production │ production │ 39c3133        │                    │ true     │
│ 8887 │ 8886   │ develop    │ develop    │ develop    │ cb2784f        │ │ false    │

Last updated: March 25, 2024

Relevant to

  • Node.js
  • WordPress