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.1
Latest Stable: 1.1
Web: http://wpengine.com/mercury
Project Lead: Tomás Puig
Contributors: Mark Kelnar, Doug Stewart, Zach Brown, RC Johnson, Jason Cohen, Kailey Lampert, Cameron Benedict, and Grant Landram, Ryan Oeltjenbruns, Lowell Vaughn
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
- Optional, but highly recommended: Install the Vagrant Hostsupdater plugin
- Short version:
vagrant plugin install vagrant-hostsupdater
- 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
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.dev 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-hostsupdater plugin, that is):
- hgv.dev -- General documentation and links for all of the tools
- hhvm.hgv.dev -- A new WordPress installation running on HHVM
- php.hgv.dev -- A new WordPress installation running on PHP-FPM (PHP 5.5)
- admin.hgv.dev -- Useful administrative tools (phpMyAdmin, etc.)
If you did not install the vagrant-hostsupdater plugin, you will need to manually add the following host entries to your host operating system's host files:
192.168.150.20 hgv.dev
192.168.150.20 admin.hgv.dev
192.168.150.20 hhvm.hgv.dev
192.168.150.20 php.hgv.dev
192.168.150.20 cache.hhvm.hgv.dev
192.168.150.20 cache.php.hgv.dev
192.168.150.20 xhprof.hgv.dev
There are two default WordPress installations provided. Both have an admin user wordpress with a password wordpress (so secure!) already created.
php.hgv.dev 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.dev 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 VirtualBox's shared 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/php and [HGV directory]/hgv_data/sites/hhvm 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|php]/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.dev/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 enabled by default for the site based on PHP-FPM. Additionally, the WordPress installs have the following constants defined:
define('WP_DEBUG', true);
define('WP_DEBUG_DISPLAY', false);
define('SCRIPT_DEBUG', true);
define('SAVEQUERIES', true);Enabling the Query Monitor WordPress plugin will allow logged-in users to view the useful debug information output by Xdebug, such as number of queries, number of objects, page render time, etc.
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.dev.
Initially, there will be no profiling data -- you'll need to enable profiling for the various HGV sites. You can enable profiling by passing _profile=1 to any PHP request on the host. To get started, visit:
Passing the _profile=1 argument to the sites causes XHProf to set a cookie. While this cookie is active, XHProf will attempt to profile all of your page views. Visit a few URLs on your PHP and HHVM sites, then visit xhprof.hgv.dev again. You should see profiling results displayed for your interactions with the sites.
When you want to disable profiling, simply append _profile=0 to any request, or visit these links:
Visiting those links should delete the cookie and disable XHProf.
HGV contains several useful tools for gathering system state and for administering individual aspects of the system.
phpMyAdmin is available at admin.hgv.dev/phpmyadmin/. The username is root and the password is blank.
phpMemcachedAdmin is available at admin.hgv.dev/phpmemcachedadmin/. You may use this tool to check on the status of the WordPress object cache.
PML is available at admin.hgv.dev/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.
For detailed how to install guides per OS and other debugging information please see the wiki here on github.
One of the great features of Vagrant is it allows developers to work locally on an environment that is as close as possible to their production environment. While VVV is an excellent WordPress development environment, it does not match any one hosting provider’s stack, it simply offers a common configuration. HGV allows you to code locally on an environment that simulates the WP Engine Mercury platform, a highly tuned WordPress stack with forward looking technology not widely offered in the hosting ecosystem. WP Engine has worked closely with Facebook to tune HHVM for the needs of WordPress, so you won’t get these constantly updating and improving configurations anywhere else.
HGV is Open Source and GPLv2.
You can set that up manually, but currently there’s no automatic way to provision this and it is not supported in our documentation at this time.
From within the same directory you did “vagrant up” originally, type “vagrant destroy”. The virtual machine will be destroyed (along with anything in it, so be sure to backup your databases!) and you can safely delete the directory if you don’t need to save any files within it. HGV is continually improving, so feel free to reinstall and “destroy” as many times as you’d like!
Yes! HGV is open-sourced and hosted on GitHub. We encourage all users to submit bug reports and pull requests with features they would like to see. See the contributing file for how to start and rules.
Due to the way that Ubuntu configures its users, you may encounter this error the first time you run vagrant up or vagrant provision. It can safely be ignored and the provisioning process itself should remove the error on subsequent runs.