Skip to content

Data sync config file

Data sync config files are necessary for running a data sync from a WordPress multisite production environment to a non-production environment. The values added to a data sync config file determine the search and replace operations that occur for the domain values of each network site in the synced database.

Create a config file

A data sync config file must be created for each non-production environment in order to perform a data sync to that environment.

If the target environment for a data sync does not yet have a data sync config file, an error message will be displayed in the Data sync panel of the VIP Dashboard that warns: “Missing .vip.yml config”

To create a config file for the target environment, select the button labeled “Create” located to the right of the error message.

An automated blank config file will be created for the environment in the /config/ directory at the root of an application’s GitHub repository. A /config/ directory will be created if it does not yet exist in the repository.

File location

Data sync config files must be located within a /config/ directory at the root of an application’s wpcomvip GitHub repository in the default branch. The default branch is usually the branch that deploys to the production environment (e.g., production or master). A /config/ directory can be added if it does not yet exist.

The /config/ directory and data sync config file(s) added to the root of the branch 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/

The data sync config file for each non-production environment must be located in the /config/ directory in the branch that deploys to the production environment.

File naming

It is possible to have multiple applications or environments using the same wpcomvip GitHub repository. In order to sync data from a production environment to it’s associated non-production environment(s), each environment must have its own 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-type].yml

In this file naming convention:

  • [app] is the name/slug used to identify an application.
  • [environment-type] is the environment type for which the config file is created.

For example, a file named .vip.example.develop.yml would be used for syncing data to an “example” application’s “develop” environment type.

In some (very rare) circumstances, an application might have more than one environment of the same type (e.g. multiple develop environments). In this case, a specific develop environment must be targeted by appending its unique name value in the naming of the environment config file:
.vip.[app].[environment-type].[name].yml

An example of this file naming convention:
.vip.example.develop.instance-01.yml

A list of environments belonging to an application and their type and name values can be retrieved with VIP-CLI.

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.

The values added to a data sync config file determine the search and replace operations that occur for the domain values of each network site in the synced database.

If the domain values for a network site are not added to the data sync config file correctly, after the data sync the network site on the target environment will have the production network site’s domain values.

  • YAML-based config files require spaces for indents, and indents are critical to YAML syntax. VIP recommends using two spaces for indents.
  • 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 include www. If www is redirected to a non-www URL, then configure the sync without www.
  • Multisite environments might 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.
  • In some cases prepending the domain values with a / may be required in order for the search and replace operation to complete as expected. Database values that contain escaped strings, such as http:\/\/example.com, will need the prepended / in order to be successfully found and replaced with a new value (e.g. http:\/\/example-com-develop.go-vip.net). An example of this structure in the config file: /example.com: /example-com-develop.go-vip.net.
  • The config files must be kept up to date as new network sites are added, and as updates are made to the assigned domain structures of each site.

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:

  1. en.example.com
  2. fr.example.com

To a non-production environment that has two corresponding network sites set to the following domains:

  1. en-preprod.example.com
  2. 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: July 11, 2024

Relevant to

  • WordPress