In this second of our three-part series on the Graph Kit for PHP (see Part 1), we’ll discuss how to virtualize your Graph Kit development environment using Vagrant, VirtualBox, and Ansible.
Virtual Development Environments FTW
A virtual development environment is one which lives on your computer while being completely isolated from your computer. The benefits are many, my favorite being the ability to test new programming software, applications, frameworks, and ideas without having to update, reconfigure, or otherwise modify the development environment on my computer.
The virtualized environment we’ll be looking at today uses VirtualBox to run a guest operating system (Ubuntu 14.04 64-bit), Vagrant to create and destroy the environment, and Ansible to provision, or install and configure, the environment. What that means for you is that you can have a fully functional development installation of the Graph Kit for PHP as easily as typing a single command into your terminal.
Installing the Tools
Installing VirtualBox and Vagrant is as simple as a quick download and installation. Grab the appropriate Vagrant installer and VirtualBox installer for your operating system, install them, and move on to the next step.
There are a few more options for Ansible, but installation remains pretty straightforward. I develop on a Mac and I’m a big fan of homebrew, so I jumped into my terminal and ran
brew install ansible. If you’re on a *nix variant, you’ll be able to find Ansible in your package manager or, if you prefer, you can install the latest version via pip.
Windows users: You won’t be installing Ansible at all. Since Ansible can’t be installed on Windows, you’d normally be out of luck. Since we used phansible to build the VM, and since they have a nifty workaround for Windows users, you’re good to go after installing Vagrant and VirtualBox.
Installing the Graph Kit
Obtaining the latest version of the Graph Kit source code is as easy as (pick one):
- Download the latest release from GitHub
- Clone the project using git:
git clone email@example.com:GraphStory/graph-kit-php.git
- Using Composer:
php composer.phar create-project graphstory/graph-kit-php graph-kit-php
TIP: If you haven’t yet, you might want to install git as well. It will make installation of and updating the Graph Kit to newer versions much simpler. As a bonus, using a version control system is a development best practice, so two birds with one stone and all that.
In order to connect to your Graph Story graph database instance, you’ll need to have your database connection settings and credentials. You can find these in the Graphs section in your account in the Graph Story Console.
Once you get them, they’ll go in a file named
/path/to/graph-kit-php/config/secret.php. The file contents look like the following (with your connection info included, of course):
<?php return array( 'graphStory' => array( 'restUsername' => 'user', 'restPassword' => 'password', 'restHost' => 'https://your-graph.do-stories.graphstory.com:7473', 'restPort' => 7473, 'https' => false, ), );
Running the VM
Open your terminal, cd into the directory where you’ve installed the Graph Kit (Mine is in
/Users/jeremykendall/dev/graph-story/graph-kit-php), and run the following:
That’s all there is to it – PHP Virtualization completed! You’ve got a virtual development environment set up, and the Graph Kit for PHP is ready to go! Visit http://graph-kit-php.dev in your browser and get started!
The first time you run vagrant up you’ll wait a few minutes for the Vagrant box to import and for Ansible to provision your environment. All subsequent runs of
vagrant up will usually run in about 30 seconds.
Here are a few handy commands to use when you’re working with a Vagrant virtual environment. All of these commands should be run from the terminal in your graph-kit-php directory.
vagrant status: Reports on the current status of the virtual machine.
vagrant up: This is the command you’ll use to start your virtual environment. The first time it runs it will provision the virtual machine. All subsequent runs will only start the VM but won’t do any provisioning.
vagrant ssh: Use this command to ssh into your virtual machine.
vagrant halt: This command halts the VM. Think of it as shutting down your computer, but for your virtual environment.
vagrant destroy: This will halt and destroy the VM, removing all of the VM’s files. Do this when you’re done with a VM or when you’d like to blow everything away and start fresh.
Interacting with the Graph Kit Source
Just because the Graph Kit source code is on a VM doesn’t mean it’s complicated to work with. Through the magic of Vagrant synced folders, the Graph Kit installation directory is shared with the Virtual Machine. Simply point your IDE of choice to the directory where you installed the Graph Kit and dig right in.
Any changes you make in the source code on your computer are reflected in the VM. This allows for the best of both worlds – using all of your everyday tools for programming while isolating your development environment.
You’re up and running with a VM packed full of graph goodness, and it’s isolated, portable, and reproducible. Not only is this a great way to work with the Graph Kit, but it’s a great development best practice as well. As you begin to write your own applications on the Graph Story platform, you might consider doing so in a virtualized environment.
If you have any problems with these instructions, or if you have any questions about the Graph Kit, please hit us up at firstname.lastname@example.org. We look forward to hearing from you!