HGV + Git Push
Mercury Vagrant (HGV) is a swiss army knife of sorts. The coolest feature is that you can test HHVM and PHP environments right next to each other. This is great for testing compatibility of plugins and the like with ease.
HGV also has an extremely similar stack to the software stack that WP Engine uses- that’s what we’re going to talk about and get set up. The main difference is that HGV uses PHP-FPM whereas the WP Engine stack uses Apache2 and mod_php. Keep this in mind because later we will be configuring the development environment to ignore the .htaccess (no Apache, no .htaccess!).
Caching is probably the most common issue plugins and themes run into with the standard WP Engine stack. With HGV setup for testing, you can test with caching on and off simultaneously in a local environment before deploying code.
Let’s get started.
Prerequisites
This guide will require that you have knowledge of Git and Vagrant. If you need more information about these, please see the following links:
Please see the prerequisites guide for HGV by clicking here if you have more questions on this part of the initial setup.
You will also want to make sure that you take the optional Vagrant Hostsupdater step listed in that guide as we are going to assume it is in place later. You can choose to use either VirtualBox or VMware hosted hypervisor when setting up Vagrant- the difference is not important to this guide.
Git Push Setup
In order to make our deployments simple, we will take advantage of the WP Engine git push integration. Much like the last step, we already have an entire guide written out regarding the setup of this! You can find it by clicking here.
This guide is assuming that you are only going to be using one developer key for all installs that you are working with. Additionally, in the bit that has you naming remotes and doing the first commit, don’t worry about that just yet. We will discuss the preferred way of doing it later on. Essentially, you just want to be sure that you have a public/private key pair and that WP Engine has your public key.
Our First Commit
We may want to rollback any changes from here on out. Since you’ve already installed HGV earlier, navigate over to the directory at hgv/hgv_data/sites/php
. Once you’re there, run the following commands:
Now, anytime that you want to go back to the initial state, you will have a commit there waiting for you! This is especially useful if you accidentially remove or overwrite the wp-config.php.
Adding a .gitignore
We will want to add a .gitignore that doesn’t track core files or the wp-config.php. This will allow us to deploy code that is relevant to the application and not mess up any core files. Since WP Engine provides updates for core on behalf of the customer, accidentally reverting an update is unwanted. Let’s run the following commands from within the same directory we were just in:
Setting Up Git Remotes
As you are probably already aware, when adding a remote to a git repository, you can name it whatever you would like. We would suggest that you name the production and staging remote after the install it’s a part of. This way, you will have to explicitly declare where you are sending files when you push a commit.
Start off by running ssh [email protected] info
. You should see something like this:
Adding them as remotes is pretty straightforward. Take a look at the follow commands and replace the install_name
with your particular install name:
Lastly, just confirm that the remotes have been added with the correct names.
With that done, we move on to the last step: retrieving actual content for this development environment.
Bringing in the Content
There are a few ways that we can bring in the content to populate the development server. Our documentation over at wpengine.com/git will suggest downloading a backup (checkpoint). The checkpoint will not contain the /uploads
folder however.
We believe than an easier approach is to simply use SFTP to pull the data down. If you are using SFTP on the command line, it’s relatively easy to do a recursive get of the files. If you’re using an SFTP program with a GUI like FileZilla, it’s simply a matter of dragging and dropping.
All you need to pull into hgv_data/sites/php
is the wp-content/
folder. You can bring the core files if you would like, but since we’re not tracking them in the git repository, it won’t matter too much either way- you decide.
This method of pulling data down will be useful later on when you’re working in this environment regularly. You push with Git and then pull with SFTP. If you attempt to pull with Git, you won’t be pulling from the server. The Git Push system will simply look at the history of what has been pushed and then attempt to reconcile your request against that history. Thus, the best way to make sure you’re getting what is on the server is to pull directly off of it with SFTP.
Once the wp-content/
is in place, you will need to drop the current database for the PHP site and replace it with the database found at wp-content/mysql.sql. If you prefer using a GUI, you can use http://admin.hgv.dev/phpmyadmin/ (username: root, password: blank).
If you would like to use the command line and wp-cli (my personal favorite), first navigate to the parent directory of hgv_data
. Type vagrant ssh
to hop into the virtual machine. Then change directory to /nas/wp/www/sites/php
. Type wp db reset
to drop the current tables. Then type wp db import wp-content/mysql.sql
to import the database- done! Go ahead and hop back out of the box with ctrl+d or exit
.
Navigate back up to hgv_data/sites/php
. Let’s start tracking the new files and commit their addition with this bit:
And we’re done! The setup is complete at this point; the rest is just a matter of workflow.
Workflow
Turning it on
Let’s say that you want to start working on something in this environment. If you’re just working on a plugin, you probably won’t even need to replace the default WordPress install that is in HGV. If you’re working with a specific site, you’ll need some way to make sure you’re seeing the HGV version of the site and not the live one. If you’re looking at using your own domain, please click here to see the official stance from the HGV documentation.
With that in mind, let’s take a look at using some of the built-in tools that will let us avoid using your own domain (and instead use a development domain!). The URL for the PHP environment is php.hgv.dev
.
Navigate over to the root hgv directory you have set up and run vagrant up
. Once the box is up, type vagrant ssh
to dive in. Once you’re in, run the following commands (and replace your-domain.com with your domain):
Success! You should be able to go to php.hgv.dev and cache.php.hgv.dev and see your site now.
Testing
Go ahead and hop out of the Vagrant machine and back into your normal “host” computer. If you would like to edit to code, the place to do it is on the host side of things. Open up the files with your favorite text editor, make some changes, and save. The changes will be automagically reflected over to the Vagrant so you should be able to immediately test out the site.
Much like before, you can go to php.hgv.dev and cache.php.hgv.dev and see the changes made immediately (with and without cache!). That’s about it.
Deployment
Once you have made a few changes to the code, you’ll need to go ahead and commit your changes. For anyone familiar with Git, you’ll know that you just need to run something like git commit -am 'I made changes!'
. If you’re not familiar with Git and yet still this far in the guide- I’m impressed.
Once you have your changes saved, hop back into the box and navigate to the php site’s directory. Run another search and replace that looks like this:
Hop out of the Vagrant, commit once more. If you dumped the database, the new changes should be tracked.
Once you’re ready to deploy, use git remote -v
to find your remote repository names. We like to deploy to staging first, and, if it looks good, search-replace to the live domain and then push to production. If you want to be slightly faster and slightly looser, you can deploy straight to the production remote.
And that’s it! You’ve now set up and used HGV to build and test code locally and then deploy it to staging and production servers.
Wrapping Up
Here we are at the end of the road. Keep in mind that this guide is only intended to get you started with thinking about how to build out a workflow that takes advantage of HGV. The plethora of built in debugging tools are great in helping develop solid applications that run on the WP Engine platform. We hope you enjoy developing with Mercury Vagrant as much as we do!