This is a forked repo of the Mercury environment as it is no longer supported by WPEngine.
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/jasondemeuse/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. - If errors are encountered after the VM is created but before hgv finishes installation, run
vagrant provisionto continue
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: