Skip to content

How-to Guides

Technical References

Set up a VIP Go local development environment for Windows

For non-Windows-specific development, please see our local development documentation.

Prerequisites

Everything in this task list assumes you have administrative access to the host machine. For Windows 10 hosts, any command prompt, PowerShell, VS Code instance which is run must be Run as Administrator.

Directions

Step 1

On Windows 10, install Git for Windows and the OpenSSH client.

Step 2

Enable the OpenSSH Authentication Agent service for automatic starting, which is disabled by default. Then add the SSH key associated with your Github account to the agent via PowerShell or command prompt. Create a key first if necessary, then run:
ssh-add {path_to_public_key}

Step 3

Configure Git to use OpenSSH, and increase the size of Git packages and buffers to allow large file and pack transfers. Add the following settings to your user profiles .gitconfig, the sections are listed, do not create duplicate sections, append if needed.

[core]
    autocrlf = true
    sshCommand = C:\\\\Windows\\\\System32\\\\OpenSSH\\\\ssh.exe
    packedGitLimit = 128m
    packedGitWindowSize = 128m
[pack]
    deltaCacheSize = 128m
    packSizeLimit = 128m
    windowMemory = 128m
[http]
    postBuffer = 1024m

Step 4

Run the VVV installation. If you run into issues installing, try a previous, known good VirtualBox version. Follow through running vagrant up for the first time, additional sites can be added later.Later instructions will refer to the base installation folder for VVV, where you checked it out, as {vvv_path}.

Step 5

Create a new VVV site definition inside config/config.yml for the site with the custom site template, for instance this example creates a site at https://vipgo.test:

vipgo:
  repo: https://github.com/Varying-Vagrant-Vagrants/custom-site-template
  hosts:
    - vipgo.test
  custom:
    wp_type: subdirectory
    wpconfig_constants:
      WP_ALLOW_MULTISITE: true
      MULTISITE: true
      SUBDOMAIN_INSTALL: false
      DOMAIN_CURRENT_SITE: "vipgo.test"
      PATH_CURRENT_SITE: "/"
      SITE_ID_CURRENT_SITE: 1
      BLOG_ID_CURRENT_SITE: 1
      WP_DEBUG: true
      WP_DEBUG_LOG: true
      WP_DEBUG_DISPLAY: true
      SCRIPT_DEBUG: true
      VIP_GO_APP_ENVIRONMENT: true
      DISALLOW_FILE_EDIT: true
      DISALLOW_FILE_MODS: true
      AUTOMATIC_UPDATER_DISABLED: true

Enable helpful utilities by modifying the config files utilities section:

utilities:
  core:
    - memcached-admin
    - opcache-status
    - phpmyadmin
    - webgrind
    - trusted-hosts
    - tls-ca

Finally, increase the resources, and optionally add a static IP to your instance. In my case, my VirtualBox network uses 192.168.56.0/24, and I am assigning the instance the IP 192.168.56.75. Remove the private_network_ip and network_ip lines if not needed.

vm_config:
  memory: 4096
  cores: 2
  private_network_ip: 192.168.56.75
  network_ip: 192.168.56.75

Step 6

Copy the database dump SQL file you have to database/sql/backups directory, and change the name to match the site definition name, in this example vipgo. If you do this before you reprovision, it will load this dump file when provisioning as the sites database. You can do a find/replace on the file before loading (may be slow with a large file), or use WP CLI inside the instance to change the domain names.

Step 7

Reprovision the instance to create the new site:

vagrant reload --provision

Step 8

Add an .htaccess file to support the multisite instance in {vvv_path}/www/vipgo/public_html/:

RewriteEngine On
RewriteBase /
RewriteRule ^index\.php$ - [L]

RewriteRule ^([_0-9a-zA-Z-]+/)?wp-admin$ $1wp-admin/ [R=301,L]

RewriteCond %{REQUEST_FILENAME} -f [OR]
RewriteCond %{REQUEST_FILENAME} -d
RewriteRule ^ - [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(wp-(content|admin|includes).*) $2 [L]
RewriteRule ^([_0-9a-zA-Z-]+/)?(.*\.php)$ $2 [L]
RewriteRule . index.php [L]

Step 9

The VIP repository is hosted in the sites wp-content directory, you need to empty it first. In this example, find it at {vvv_path}/www/vipgo/public_html/wp-content/.

Step 10

Clone the sites VIP go instance repository, URL of {instance_url} the folder:

git clone {instance_url} --recursive {vvv_path}/www/vipgo/public_html/wp-content

Step 11

Pull all of the VIP Go MU plugins into your VVV instance. Note: this only works if you have a SSH key associated with a Github account. If there are any failures, please check your Git configuration accepts the larger pack and buffer sizes specified above.

This only works if you have a SSH key associated with a Github account. If there are any failures, please check your Git configuration accepts the larger pack and buffer sizes specified above.

git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive {vvv_path}/www/vipgo/public_html/wp-content/mu-plugins/

Step 12

Add the VIP Go configuration from your site repository into the VVV site configuration located at {vvv_path}/www/vipgo/public_html/wp-config.php. Locate the comment \/* That’s all, stop editing! Happy blogging. *\/ and place this block above it:

if ( file_exists( __DIR__ . '/wp-content/vip-config/vip-config.php' ) ) {
    require_once( __DIR__ . '/wp-content/vip-config/vip-config.php' );
}

Step 13

If you run into any issues with missing plugins, either mu-plugins or from your site repository, you likely need to pull the Git submodule. To do this, clear the plugin directory then reinitialize the plugin. For instance, assume the plugin name is plugins/polldaddy, and from the command prompt run:

git submodule update --init plugins/polldaddy

Step 14

Perform a WP CLI search-replace to update domain names and links. In this example, assume the initial domain name is prod-vip.go, which will be replaced with vipgo.test. From a command prompt, in a directory inside the {vvv_path}, SSH into the Vagrant instance:

vagrant ssh

Then switch to the site path, in this example, /srv/www/vipgo/public_html/, and run the following search-replace:

wp search-replace 'prod-vip.go' 'vipgo.test' --recurse-objects --all-tables --skip-tables=wp_*users

Step 15

If you don’t already have a functional user for the site, you can add one using WP CLI, again via Vagrant SSH in the example directory of /srv/www/vipgo/public_html/:

wp user create bobross happy@little.trees --role=administrator
wp super-admin add bobross

Make sure you record the password printed to the console so you can successfully login.

Step 16

In order to use VVV certificates and avoid security warnings, you need to add the certificate authority as a Trusted Root CA. You can find instructions to update your host system here. On Windows 10, this is done from a command prompt on the host using the following command:

certutil -enterprise -f -v -AddStore "Root" "certificates/ca/ca.crt"

Step 17

For Windows 10 users hosting on VirtualBox and needing to cross-browser test in Microsoft Edge, there is currently an issue with connecting to the VirtualBox Host Adapter. You can disable this by modifying the *NdisDeviceType registry key of the adapter, and setting the value to 0 from 1. You need to identify the correct adapter, referenced in the following path by {adpater_id}:

HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Class\{4d36e972-e325-11ce-bfc1-08002be10318}\{adapter_id}\*NdisDeviceType

Reboot after changing this setting, make sure you vagrant up, then test. Do this at your own risk.

Git for Windows

OpenSSH Installation

VVV CA Certificate

VVV Custom Site Template

VVV Installation

VVV Instance HTTPS

VVV System Requirements

Thanks to Ryan Leeson of Trellist for the work in putting this guide together.

Last updated: October 20, 2020