Configuration file for a VIP Local Development Environment

A custom configuration file enables a VIP Local Development Environment with specific settings to be created in a repeatable manner. If the configuration file is committed to an application’s source-controlled GitHub repository, multiple team members with access to that repository can use the file to create VIP Local Development Environments with identical settings.

Create a configuration file

In the GitHub repository that has been git-cloned to the user’s local machine:

1. Create a .wpvip directory in the root of the repository if one does not yet exist.
2. In the .wpvip directory, create either a YML file named vip-dev-env.yml or an EJS file named vip-dev-env.yml.ejs.

For example, if an application repository named “example-repo” was cloned to a user’s desktop, the absolute path for the YML configuration file would be similar to: /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml

Minimum requirement

At minimum, for a configuration file to be valid for the creation of a VIP Local Development Environment, it must define values for the options configuration-version and slug.

In this example, the configuration file is populated with the minimum required options configuration-version defined as 1 (no other value is accepted) and slug defined as example-site:

configuration-version: 1
slug: example-site

Because --slug is defined in a configuration file, all vip dev-env commands that are run from within the root of a repository that contains .wpvip/vip-dev-env.yml will automatically target the environment created with that configuration file without passing the --slug option and its value.

Add options and values

All of the options that can be set in the VIP-CLI command vip dev-env create can also be set in the configuration file.

This example demonstrates multiple options and their values set in the configuration file:

configuration-version: 1
slug: example-site
title: Local Example Site
multisite: false
php: 8.2
wordpress: 6.7
mu-plugins: demo
app-code: demo
media-redirect-domain: www.example.com
elasticsearch: true
phpmyadmin: false
mailpit: false
xdebug: false
photon: false
cron: true

Options that are not defined in the configuration file

During the creation or update of a local environment, the setup wizard will prompt for any options that are either not defined in the configuration file or are defined with invalid values.

In this example output, the setup wizard prompts for a version of PHP when a local environment is created with a configuration file that does not define php:

$ vip dev-env create
Using environment example-site from /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml

? PHP version to use … 
❯ 8.2 (recommended)
  8.1
  8.3
  8.4 (experimental)

Any options that are not defined in the configuration file can also be set in the initial vip dev-env create VIP-CLI command.

In this example, the PHP version is set to 8.2 by passing --php=8.2 in the vip dev-env create command:

$ vip dev-env create --php=8.2
Using environment example-site from /Users/yoli/Desktop/example-repo/.wpvip/vip-dev-env.yml

 SLUG              example-site                                                                                          
 LOCATION          /Users/yoli/.local/share/vip/dev-environment/example-site                                             
 SERVICES          nginx, php, database, memcached, elasticsearch, wordpress, vip-mu-plugins                             
 NGINX URLS        http://example-site.vipdev.lndo.site/                                                                 
                   https://example-site.vipdev.lndo.site/                                                                
 STATUS            DOWN                                                                                                  
 LOGIN URL         http://example-site.vipdev.lndo.site/wp-admin/?vip-dev-autologin=8bbc27e6-6cd9-4809-9b52-e2cb95b51700 
 DEFAULT USERNAME  vipgo                                                                                                 
 DEFAULT PASSWORD  password                                                                                              
 DOCUMENTATION     https://docs.wpvip.com/vip-local-development-environment/                                             

✓ environment created.

To start the environment run:

vip dev-env start

To interact with the environment, it must first be brought into a running state with vip dev-env start.

Apply a configuration file to a local environment

A relationship to an existing configuration file can be established with a local environment at the time it is created with the vip dev-env create VIP-CLI command.

The command that creates the new environment must be run from within a directory where the configuration file has the relative path .wpvip/vip-dev-env.yml. This is typically the root of the locally git-cloned application repository.

If the command vip dev-env create is run from the correct location, the output will confirm that the local environment has successfully been created based on the configuration file.

In this example, the output message Using environment example-site from /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml confirms that the new environment has been created based on the configuration file:

$ vip dev-env create
Using environment example-site from /Users/username/Desktop/example-repo/.wpvip/vip-dev-env.yml

 SLUG              example-site                                                                                          
 LOCATION          /Users/username/.local/share/vip/dev-environment/example-site                                             
 SERVICES          nginx, php, database, memcached, elasticsearch, wordpress, vip-mu-plugins                             
 NGINX URLS        http://example-site.vipdev.lndo.site/                                                                 
                   https://example-site.vipdev.lndo.site/                                                                
 STATUS            DOWN                                                                                                  
 LOGIN URL         http://example-site.vipdev.lndo.site/wp-admin/?vip-dev-autologin=3e952c17-8402-4753-b5e0-d7ec4710fa09 
 DEFAULT USERNAME  vipgo                                                                                                 
 DEFAULT PASSWORD  password                                                                                              
 DOCUMENTATION     https://docs.wpvip.com/vip-local-development-environment/                                             

✓ environment created.

To start the environment run:

vip dev-env start

Apply a configuration file to an existing environment

A relationship with a configuration file can be created with a local environment that already exists if:

• The value of slug in the configuration file is updated to match the slug of the existing environment
• The command vip dev-env update is run from within a directory where the updated configuration file has the relative path .wpvip/vip-dev-env.yml.

This example output demonstrates the results of the vip dev-env update command after a configuration file was modified to associate with an existing local environment with the assigned slug vip-local:

$ vip dev-env update
Using environment vip-local from /Users/yoli/Desktop/example-repo/.wpvip/vip-dev-env.yml

Backup of .lando.yml was created in /Users/yoli/.local/share/vip/dev-environment/vip-local/.lando.backup.yml

✓ environment updated. Please start environment again for changes to take effect: vip dev-env --slug vip-local start

For the settings in the configuration file to have an effect, the running environment must be restarted with vip dev-env start.

Update the configuration file

Once a local environment has been created with a configuration file, edits can be made to the options and values in the configuration file at any time.

For the configuration file update to take effect on the local environment:

1. Save the configuration file in its updated state.
2. Run the command vip dev-env update.
3. Run the command vip dev-env start.

Override an option with a VIP-CLI command

Any option set in a configuration file—except for slug—can be temporarily overridden by passing a new value for that option in a vip dev-env update VIP-CLI command.

For example, to override the PHP version that is set to php: 8.1 in a configuration file:

1. Set the PHP version to 8.2 with the command vip dev-env update --php=8.2.
2. Restart the environment with the command vip dev-env start.

The local environment will run PHP version 8.2 until the override is disabled.

To disable the override

To remove an override and update the local environment to fall back to the configuration file for all options:

1. Run the command vip dev-env update.
2. Restart the environment with the command vip dev-env start.

Advanced overrides

Settings can also be added to the configuration file to automatically generate a custom .lando.local.yml for a local environment.

Below the standard options in a configuration file, add an overrides: section where custom settings for services and tooling can be defined.

Settings that are defined in the overrides: section of a configuration file will be copied into  .lando.local.yml for the local environment that is created with that configuration file.

An example of these settings can be reviewed in the VIP Integrations Starter Kit.

Edits can be made to the configuration file at any time, but for the changes to take effect the local environment must be updated (i.e. vip dev-env update) and restarted (i.e. vip dev-env update).