A simple Vagrant boilerplate setup (configured using the PuPHPet GUI).
Project directory structure
This config assumes your projects have a directory structure that looks something like this:
myproject/ myproject/site/ myproject/shared/
We track our projects one directory up from the site's webroot, which is usually
myproject/site/public_html/. Therefore, you should clone your main project repo into the
All assets you don't want tracked by git (such as environment config files, cache folders, media upload folders etc.) should be symlinked from their default locations in
Important: Don't run anything yet, such as
bower install etc. on your project. You should only do this once your Vagrant box is up-and-running and you are logged in to the ssh shell.
Essentially you have two options:
- Download this repo, and put all the contents (except
README.md) into the
- Or, take just the config.yaml file from this repo and drop it onto the puphpet.com webpage, enabling you to modify all the settings at will and create your own manifest.
Whether you choose to download this repo or just use the
config.yaml file with puphpet.com, you will need to change all instances of 'myproject' in
config.yaml to the actual name of your project.
You should also make sure the paths in
config.yaml, specifically the
vhosts settings, reflect your own environment - again, we are assuming your webroot is
myproject/site/public_html/, but if it's not you'll need to find the relevant section in
config.yaml and change it.
Either way, it's worth familiarising yourself with puphpet.com to see what options are available to you.
Adding your own dotfiles and shell scripts
- Put your own dotfiles in
- Put your own shell scripts in
Node, Grunt, Bower and Compass
If you choose to use this repo as-is, we have already added a shell script to
myproject/site/puphpet/files/exec-once that installs Node, Grunt-cli, Bower and Compass.
You can find out more about this on the Server section of the PuPHPet website.
Modifying your hosts file
On a Mac (and Linux I believe) the
hosts files can be found in
/etc/hosts. Simply add a new entry to the end of this file:
Note: The IP address should match the IP address found in
By default when you first
vagrant up an
id_rsa.pub file unique to your VM will be created in
/puphpet/files/dot/ssh. However, you will probably want to replace these with your own
id_rsa.pub files so you can connect to remote private Git repos as usual. Either do this after the first
vagrant up, or just put them in the
/puphpet/files/dot/ssh directory before the first provisioning and new ones won't be created.
You may also need to add a
config file in your host computer's
~/.ssh folder that contains the following:
Host * ForwardAgent yes
This allows the host computer's SSH agent to forward requests from your VM.
vagrant commands should be run from your
myproject/site/ directory (and not from 'inside' the virtual machine)
In order to set up your virtual machine for the first time (fair warning - this could take quite a while), or to restart it if you've halted it you need to run:
$ vagrant up
Note: During the 'up' process you may be asked for a password in order to mount the NFS shared folders. You should enter your host machine's user password.
Once the machine has started up and installed all its dependencies you can log in to the machine using:
$ vagrant ssh
You can now do all your command line work on your project from within the Vagrant box ssh shell.
You can put the machine to sleep by running:
$ vagrant halt
You can also just exit the machine (leaving it running in the background):
Note: This command you would run from 'inside' the virtual machine.
If, after having already set up the machine, you add additional shell scripts to
myproject/site/puphpet/files/exec-always you can provision these by running:
$ vagrant provision
You can get rid of the machine by running:
$ vagrant destroy
The first time you 'up' the box you should set your Git user name and email. Run these two commands consecutively:
$ git config --global user.name "Your Name"
$ git config --global user.email firstname.lastname@example.org
What on earth are Vagrant, Puppet, PuPHPet? Read on...