This project is meant to allow people in the WordPress community to run a single Vagrant for developing, debugging, and deploying HHVM based code. We have also added standard PHP to test against so that this project is useful for more standard development as well.
The project is also intended as a tool for allowing WP Engine users to test their code prior to actual deployment on WP Engine "Mercury" infrastructure. This is not intended as an exact replica of WP Engine's infrastructure, but is instead a "simulator" of the conditions and software stack on WPE's Mercury platform, allowing you to develop and test your code with an end goal of stability and compatibility with Mercury.
Mercury differs from standard WordPress hosting in several ways, chief among which is the use of HHVM to serve all PHP code. To quote HHVM's Website:
HHVM is an open-source virtual machine designed for executing programs written in Hack and PHP. HHVM uses a just-in-time (JIT) compilation approach to achieve superior performance while maintaining the development flexibility that PHP provides.
We have some great getting started videos and guides here if you want a more guided experience.
Mercury Vagrant is a WP Engine creation in partnership with community members.
Version: 1.5.1
Latest Stable: 1.5.1
Web: https://wpengine.com/support/use-wp-engine-php7-vagrant-hgv/
Project Lead: Jason Cohen
Contributors: Mark Kelnar, Doug Stewart, Zach Brown, RC Johnson, Jason Cohen, Kailey Lampert, Cameron Benedict, Grant Landram, Ryan Oeltjenbruns, Lowell Vaughn, Rachel Baker, Eric Mann, Stephen Lin
Thanks: To the VVV team and others who have worked on the open source we've included.
In order to use HGV effectively, you'll need to have a few tools installed on your computer. You should:
- Install Git.
- Windows users: Be sure to add the Git executables to your path (See, e.g. this guide, under "Prerequisites")
- Install virtual machine software (VMware or VirtualBox are recommended).
- Install Vagrant
- Install Node
- Optional, but highly recommended: Install the Vagrant Ghost plugin
- Short version:
vagrant plugin install vagrant-ghost
- Suggestion: Development workstation/laptop should have at least 8GB of RAM. hgv needs to allocate 1GB of RAM in order to run. (Users with <=4GB of RAM [e.g. base-model MacBook Airs] have seen overall system slowness while running this Vagrant box and much of anything else.)
- Windows users should be certain that their BIOS' virtualization settings are enabled. (Intel owners should enable VT-x while AMD owners should enable AMD-v. See here for a better explanation.)
- Recommendation: This Vagrant box uses a 64 bit operating system (because HHVM requires a 64 bit OS), so we highly recommend that it only be run on 64 bit machines running 64 bit operating systems. (Most, if not all desktops and laptops sold in the last few years are running on 64 bit processors. Some may not be running 64 bit operating systems, however. Please check your system's documentation.)
git clone --recursive https://github.com/wpengine/hgv.gitto clone the latest version of the tool.- Change into the directory
hgv. - Run
npm installto install build and deploy script dependencies. - Run
vagrant up.
Two options to decide, do you delete your existing vagrant and any WP database work or b) do you run the setup scripts to update your existing vagrant environment?
A) To delete your existing HGV vagrant work and re-create from scratch
- Change into the directory
hgv. - Run
vagrant destroy. - Run
vagrant up.
B) To run the script that will update your existing vagrant
- Change into the directory
hgv. - Run
vagrant reload. - Run
vagrant provision.
HGV uses a mixture of Vagrant's shell provisioner to kick things off and then uses a tool called Ansible to complete the configuration of the system.
Once Vagrant is done provisioning the VM, you will have a box running Ubuntu 14.04 (aka Trusty Tahr) containing:
Once the VM is done provisioning, direct your browser to http://hgv.test You will receive fuller instructions on the use of this Vagrant environment there.
No really, make sure you go to these to check them out as you work with HGV. HGV automatically creates four sites and adds host file entries for them (if you installed the vagrant-ghost plugin, that is):
- hgv.test -- General documentation and links for all of the tools
- hhvm.hgv.test -- A new WordPress installation running on HHVM
- php.hgv.test -- A new WordPress installation running on PHP-FPM (PHP 5.5)
- admin.hgv.test -- Useful administrative tools (phpMyAdmin, etc.)
If you did not install the vagrant-ghost plugin, you will need to manually add the following host entries to your host operating system's host files:
192.168.150.20 hgv.test
192.168.150.20 admin.hgv.test
192.168.150.20 hhvm.hgv.test
192.168.150.20 php.hgv.test
192.168.150.20 cache.hhvm.hgv.test
192.168.150.20 cache.php.hgv.test
192.168.150.20 xhprof.hgv.test
There are two default WordPress installations provided. Both have an admin user wordpress with a password wordpress (so secure!) already created.
php.hgv.test is a basic WordPress install running the latest stable version of WordPress on a fairly standard LEMP stack consisting of Nginx, PHP-FPM, and Percona DB.
hhvm.hgv.test is a basic WordPress install running the latest stable version of WordPress on top of an Nginx + HHVM + Percona DB stack.
The following URLs will let you view a specific page with caching turned on to test for dynamic content performance.
The following WordPress tools and plugins are installed on each WP site (but are not enabled) by default. We highly recommend you try them out if you have not before:
HGV utilizes Vagrant's synced folders to create a folder, hgv_data, that is accessible from both the HGV virtual machine and your operating system. This directory will be available for use after the first time the virtual machine is started using the vagrant up command. You can access the WP installations directly by going to [HGV directory]/hgv_data/sites in the Finder (Mac)/Explorer (Windows)/filesystem navigator of choice (Linux, Free/Open/NetBSD, etc.)
Installing new plugins and themes is as simple as putting themes in [HGV directory]/hgv_data/sites/hhvm/wp-content/[plugins|themes]
To connect to the Vagrant instance, type vagrant ssh from inside of the HGV directory. This will place you in the CLI on the VM.
Once you are connected to the HGV virtual machine, system and web server logs can be viewed in
/var/log . You may view the contents of the system log by typing sudo less /var/log/syslog.
Web server logs are stored in /var/log/nginx, with separate log files for every site. Each site has several log files associated with it:
[site].hgv.dev.access.log[site].hgv.dev.apachestyle.access.log[site].hgv.dev.error.log
The first two logs track web requests to the sites, while the third log tracks errors reported, both by Nginx and by "upstream" PHP and HHVM processes.
HHVM logs are in /var/log/hhvm . PHP-FPM writes all of its logging information into
/var/log/php5-fpm.log .
Sometimes, keeping tabs on a log file while hitting a site to view log messages in real-time can be helpful. To do so, run sudo tail -f [log file] from your SSH session. For example, sudo tail -f /var/log/nginx/php.hgv.dev.error.log would give you an alwaysupdating view of the error log file for the PHP-FPM-based site.
You may easily use the phpMyAdmin installation at admin.hgv.test/phpmyadmin/ (as listed above) in order to view and interact with the underlying database. However, if you are used to using a third-party GUI, such as Sequel Pro or MySQL Workbench, TCP port 3306 (the MySQL/Percona port) is forwarded from the Vagrant VM to TCP port 23306 on your actual machine. You would then configure MySQL WB or Sequel Pro to connect to localhost:23306 .
The following useful developer tools are installed by default:
PHP's Xdebug extension is installed by default for the site based on PHP-FPM. See the dashboard for details about the features that are enabled by default for each WordPress.
Xdebug browser extensions to toggle Xdebug on/off without having to ssh into the virtual machine:
- [Safari - Xdebug Toggler] (https://github.com/benmatselby/xdebug-toggler)
- [FireFox - Easiest Xdebug] (https://addons.mozilla.org/en-US/firefox/addon/the-easiest-xdebug/)
- [Chrome - Xdebug Helper] (https://chrome.google.com/webstore/detail/xdebug-helper/eadndfjplgieldjbigjakmdgkmoaaaoc)
HGV includes an advanced PHP/HHVM profiling tool, http://php.net/xhprof and a GUI for viewing results. You can view results for your HGV instance at xhprof.hgv.test. See the dashboard for details about how easy it is to turn on profiling by adding one parameter to your page request in the browser.
phpMyAdmin is available at admin.hgv.test/phpmyadmin/. The username is root and the password is blank.
phpMemcachedAdmin is available at admin.hgv.test/phpmemcachedadmin/. You may use this tool to check on the status of the WordPress object cache.
PML is available at admin.hgv.test/logs. You may use this tool to quickly view the most recent web server access and error logs for the various sites automatically created by HGV.
README.md - This README markdown file, the technical steps of how to get up and running. But not all the technical details or configuration options specific to the HGV environment.
wiki - Frequently asked questions
website - General introduction for the Mercury project along with video walkthroughs about how to setup HGV for the first time.
blog - WP Engine blogs when significant releases or updates are made to HGV.
updates - Another place where the WP Engine team will go into detail about releases or updates to HGV.
dashboard - The local HGV dashboard which is available when your vagrant is up and running. This contains all the technical details and configuration options specific to the HGV environment.
For detailed how to install guides per OS and other debugging information please see the wiki here on github.