Domain mapping config file
For WordPress multisite environments on VIP, data syncs require a domain mapping config file to exist in the application’s GitHub repository. The settings in the domain mapping config file provide values for a search and replace to occur and correctly update the domain values for each subsite in the synced database.
Domain mapping config file location
Domain mapping config files must be located in the /config/ directory of your code repository, in the branch that deploys to your production
environment (usually master
).
If the environment you are syncing down to does not yet have a domain mapping config file, the error message “Missing .vip.yml.config” will appear on the Sync section of the VIP Dashboard.
Click on the “.vip.yml.config” link to create a blank automated config file for this environment in your application’s GitHub repository.
The root of a master
branch with added domain mapping config files should have a structure similar to this example:
|-- client-mu-plugins/
|-- config/
|----- .vip.example.develop.yml
|----- .vip.example.preprod.yml
|-- images/
|-- languages/
|-- plugins/
|-- themes/
|-- vip-config/
File naming
It is possible to have multiple applications or environments using the same GitHub repository. Each of them will need a unique domain mapping config file. A specific naming convention for domain mapping config files is required for the data sync process to correctly identify the intended application and environment:
.vip.[app].[environment].yml
The placeholders are:
[app]
is the name/slug used to identify the (production) application.[environment]
is the environment that this config file applies to.
For example, a file named .vip.example.develop.yml would be used for syncing data to the “example” application’s “develop” environment.
In some (very rare) circumstances, you may have multiple environments using the same environment name (e.g. multiple develop
environments). In this case, a unique naming convention can be appended to the non-production environment config:
.vip.[app].[environment].[child].yml
An illustrated example of this:
.vip.example.develop.instance-01.yml
Structure
Setting up the domain mapping config file with the correct values and structure is essential for the data sync process to work as expected.
- YAML-based config files require spaces for indents, and indents are critical to YAML syntax. VIP recommends using two spaces for indents.
- Multisite environments can use a combination of domain values for subsites such as convenience names, custom domains, subdomains and subdirectories. For a successful data sync, the value added to the domain mapping config file for a subsite must match the exact domain value set for that subsite, both for the origin environment and the destination environment.
- If a subsite is set to a domain value that includes a
www
prefix, the domain in the configuration file for that subsite must also includewww
. Ifwww
is redirected to a non-www URL, then configure the sync withoutwww
.
An example of the basic structure of a YAML domain mapping config file:
data_sync:
domain_map:
prod-url-1: nonprod-url-1
prod-url-2: nonprod-url-2
Domain mapping config file example #1
To sync data from a production environment with two subsites set to the following domains:
en.example.com
fr.example.com
To a non-production environment that has two corresponding subsites set to the following domains:
en-preprod.example.com
fr-preprod.example.com
The following settings would be required for the domain mapping config file:
data_sync:
domain_map:
en.example.com: en-preprod.example.com
fr.example.com: fr-preprod.example.com
When data sync runs, all instances of en.example.com
will be replaced with en-preprod.example.com
and all instances of fr.example.com
will be replaced with fr-preprod.example.com
.
Domain mapping config file example #2
A third subsite is added to the production site used in the previous example with the subdirectory domain structure: example.com/translate
.
A third subsite is also added to the non-production site: preprod.example.com/translate
.
The domain mapping config file will then need to be updated to:
data_sync:
domain_map:
en.example.com: en-preprod.example.com
fr.example.com: fr-preprod.example.com
example.com/translate: preprod.example.com/translate
Maintenance
Updates must be made to domain mapping config files when subsite domains are added, removed, or modified across any of the environments.