VIP Go local development – Windows

VIP Go platform specific

This document is for sites running on VIP Go.

Learn more

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

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.

  1. On Windows 10, install Git for Windows and the OpenSSH client.
  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 neccessary, then run:
    ssh-add {path_to_public_key}
    
  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
    
  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}.
  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
    
  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.
  7. Reprovision the instance to create the new site:
    vagrant reload --provision
    
  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]
    
  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/.
  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
    
  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.
    git clone git@github.com:Automattic/vip-go-mu-plugins.git --recursive {vvv_path}/www/vipgo/public_html/wp-content/mu-plugins/
    
  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' );
    }
    
  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
    
  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
    
  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.

  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"
    
  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.

Links

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

Ready to get started?

Drop us a note.

No matter where you are in the planning process, we’re happy to help, and we’re actual humans here on the other side of the form. 👋 We’re here to discuss your challenges and plans, evaluate your existing resources or a potential partner, or even make some initial recommendations. And, of course, we’re here to help any time you’re in the market for some robust WordPress awesomeness.

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.