Data sync config file
For WordPress multisite environments on VIP, data syncs require a config file to be added to the application’s wpcomvip GitHub repository and be kept up to date. The settings in the data sync config file provide domain mapping values for a search and replace to occur and correctly update the domain values for each network site in the synced database.
Location
Data sync config files must be located in a /config/
directory added to the application’s wpcomvip GitHub repository, in the branch that deploys to the production environment, usually production
or master
.
If the target environment for the data sync does not yet have a data sync config file, the error message “Missing .vip.yml.config
” will appear in the Data sync panel of the VIP Dashboard.
Select the “.vip.yml.config” link to create an automated blank config file for the environment in the application’s GitHub repository.
The root of a the branch with added data sync 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 wpcomvip GitHub repository. Each of them will need a unique data sync config file. A specific naming convention for data sync config files is required for the data sync process to correctly identify the intended application and environment:.vip.[app].[environment].yml
In this file naming convention:
[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, multiple environments may be 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 example of this file naming convention:.vip.example.develop.instance-01.yml
Structure
Setting up the data sync 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 network sites such as convenience names, custom domains, subdomains and subdirectories. For a successful data sync, the value added to the data sync config file for a network site must match the exact domain value set for that site, both for the origin environment and the destination environment.
- If a network site is set to a domain value that includes a
www
prefix, the domain in the configuration file for that site 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 data sync config file:
data_sync:
domain_map:
prod-url-1: nonprod-url-1
prod-url-2: nonprod-url-2
Data sync config file example #1
To sync data from a production environment that has two sites on its network set to the following domains:
en.example.com
fr.example.com
To a non-production environment that has two corresponding network sites set to the following domains:
en-preprod.example.com
fr-preprod.example.com
The following settings would be required for the data sync 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
.
Data sync config file example #2
A third network site is added to the production site used in the previous example with the subdirectory domain structure: example.com/translate
.
A third network site is also added to the non-production site: preprod.example.com/translate
.
The data sync 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 data sync config files when domains for network sites are added, removed, or modified across any of the environments.
Last updated: February 27, 2023