Setting up Vagrant with Laravel 4

Jun 17, 2013

Table of contents:

Installing Vagrant
Installing VirtualBox
Setting up Vagrant
Getting a box
Booting up and SSH’ing
Synced folders
Networking
Provisioning
Provisioning Laravel 4
Conclusion

One of the things that annoys me the most about picking up someone else’s work is that it shouldn’t be difficult to get up and running. If I start exploring an Open Source project, I want to see something magical happen almost instantly or I lose interest. It’s just not worth the time to have to jump through hoops and set everything up just to see a working example.

Not having a standard environment for a project can also be a problem when you are working as part of a team of developers. If you are all using your own machines, and you all have different versions of each bit of the stack, then you can hit problems where code is written for one machine, but causes problems on another. You don’t want to be in a situation where your code passes all the tests locally, but constantly falls over as soon as it hits the production server.

This is a guide to getting started with Vagrant, and how to create an environment that is tailored to Laravel 4.

Installing Vagrant

As always, I’m using OS X. I’m not going to run through how to do this in every operating system because it is out of the scope of this tutorial.

So the first thing to do is to head over to the downloads page and install the appropriate version of Vagrant for your computer. At the time of me writing this, I will be using v1.2.2.

For OS X, the installation procedure is just the standard installer process. This process should literally take 2 minutes which is yet another beautiful reason to use Vagrant because you don’t have to install anything through Terminal or do any nasty kind of compiling.

Installing VirtualBox

Another requirement to use Vagrant is that you have a Virtual Machine provider. This is basically just software that runs the virtual machine. I’m going to be using VirtualBox because it’s free and easy to set up.

Ok, so I did say that there should be no set up, but now that you have Vagrant and VirtualBox installed there is nothing more to install, I promise. Now for every future project, you already have everything you need without having to deal with getting your environment set up for the specific requirements of the project.

Setting up Vagrant

Vagrant is basically just a configuration file (Vagrantfile) that tells the VirtualMachine what to set up. The Vagrantfile should be kept in the root of your project and should be added to Git so that anyone else who is working on the project can use the same configuration file.

So move into your project root and run the following command:

$ cd Code/cribbb
$ vagrant init

Now if you open your project in a text editor, you will see the new Vagrantfile. This can look overwhelming at first, but it’s nearly all just comments. Have a read through the comments, but if it doesn’t make sense just yet, don’t worry.

Getting a box

When you are setting up a Virtual Machine, you need the operating system and all of that junk before you even begin. Instead of requiring you to build that from scratch for yourself, Vagrant provides base images which can just be cloned to your machine. These base images are known as boxes.

This means that whenever you want to use that box, you can just set it in your Vagrantfile. The box isn’t stored in your project file, so you can make project specific changes to the box, but those changes won’t effect the original image so you can continue to use the same box with different projects.

To download an Ubuntu box, run the following command:

$ vagrant box add precise32 https://files.vagrantup.com/precise32.box

Now open up your Vagrantfile file and replace the first line with the second line:

Now Vagrant knows which box to use in this project.

Booting up and SSH’ing

Now we have a box ready to go, we can start up Vagrant.

To start Vagrant, you simply run:

$ vagrant up

You should see a load of output to the terminal and then you are just returned to the prompt. You might be thinking, “hmm that didn’t seem to do anything?”.

Vagrant doesn’t actually have a user interface. So if you are familiar with seeing the pinky/purple desktop of Ubuntu, you won’t be seeing it here.

Instead, we need to SSH into our Virtual Machine. To do that, run the following command:

$ vagrant ssh

If you have ever used Ubuntu on a server, you should be familiar with what appears now.

So now you have a full installation of Ubuntu running on your machine that you can create or destroy in seconds. How amazing is that?! Now you can mess about with your Ubuntu box until your heart is content.

To get rid of the Ubuntu box, simply exit out of SSH and then run the following command:

$ exit
$ vagrant destroy

Synced folders

Now that you have your Virtual Machine set up, how do you work on it? Vagrant actually makes this incredibly easy because you don’t have to do anything!

SSH back into the Virtual Machine and move into the /vagrant folder:

$ vagrant up
$ vagrant ssh
$ cd /vagrant
$ ls -l

You should see a list of all the files from your project. Vagrant will automatically sync all of the files from the root of where you placed your Vagrantfile earlier. This also means that you can still make changes on your local machine using your favourite text editor, and all of the changes will automatically be synced to the Virtual Machine.

Networking

Now that you have your files synced, how do you see your project in the browser? Vagrant makes this really easy with it’s port forwarding feature. This simply allows you to specify ports on the guest machine to share via a port on the host machine.

Add the following line to your Vagrantfile:

Now whenever you have Vagrant up and running, you can go to https://localhost:4567 in your browser to see your project.

Provisioning

If you have ever set up a fresh installation of Ubuntu, you will know that you have to install a load of things before you are good to go. Now that you can SSH into your machine, you can happily go about installing whatever you want to set up the machine exactly how you want it.

However, you are going to have to do this every time you start up the Virtual Machine!

Instead, we can provision the machine so that everything we need is automatically installed when we boot up. This means that any new person who works on the project doesn’t actually have to install any software on the Virtual Machine because everything will be handled automatically.

To set up provisioning, all we have to do is to create a shell script that will automatically be loaded when we boot up Vagrant.

Create a new file called bootstrap.sh in the root of your project (the same location where you saved Vagrantfile).

Next we need to tell Vagrant to run this file when it starts up. Open your Vagrantfile and add the following line under where you set the box:

Vagrant.configure("2") do |config|
    config.vm.box = "precise32"
    config.vm.provision :shell, :path => "bootstrap.sh"
end

Now whenever you start up Vagrant, the bootstrap shell script will automatically be run.

Provisioning Laravel 4

Now that we have provisioning set up, we can start adding a list of instructions for what should be provisioned whenever Vagrant is set up.

Open up your boostrap.sh file and add the following:

Set the interpreter:

#!/usr/bin/env bash

Update Ubuntu:

# Update the box
# ————-
# Downloads the package lists from the repositories
# and "updates" them to get information on the newest
# versions of packages and their dependencies
apt-get update

Install Vim:

# Install Vim
apt-get install -y vim

Set up Apache:

# Apache
# ——
# Install
apt-get install -y apache2
# Remove /var/www default
rm -rf /var/www
# Symlink /vagrant to /var/www
ln -fs /vagrant /var/www
# Add ServerName to httpd.conf
echo "ServerName localhost" > /etc/apache2/httpd.conf
# Setup hosts file
VHOST=$(cat <<EOF
<VirtualHost *:80>
DocumentRoot "/vagrant/public"
ServerName localhost
<Directory "/vagrant/public">
AllowOverride All
</Directory>
</VirtualHost>
EOF
)
echo "${VHOST}" > /etc/apache2/sites-enabled/000-default
# Enable mod_rewrite
a2enmod rewrite
# Restart apache
service apache2 restart

Install PHP 5.4:

# PHP 5.4
# ——-
apt-get install -y libapache2-mod-php5
# Add add-apt-repository binary
apt-get install -y python-software-properties
# Install PHP 5.4
add-apt-repository ppa:ondrej/php5
# Update
apt-get update

Set up other PHP stuff:

# PHP stuff
# ———
# Command-Line Interpreter
apt-get install -y php5-cli
# MySQL database connections directly from PHP
apt-get install -y php5-mysql
# cURL is a library for getting files from FTP, GOPHER, HTTP server
apt-get install -y php5-curl
# Module for MCrypt functions in PHP
apt-get install -y php5-mcrypt

Install cURL:

# cURL
# —-
apt-get install -y curl

Install MySQL:

# Mysql
# —-
# Ignore the post install questions
export DEBIAN_FRONTEND=noninteractive
# Install MySQL quietly
apt-get -q -y install mysql-server-5.5

Install Git:

# Git
# —
apt-get install git-core

Install Composer:

# Install Composer
# —————-
curl -s https://getcomposer.org/installer | php
# Make Composer available globally
mv composer.phar /usr/local/bin/composer

Set up Laravel:

# Laravel stuff
# ————-
# Load Composer packages
cd /var/www
composer install -dev
# Set up the database
echo "CREATE DATABASE IF NOT EXISTS cribbb" | mysql
echo "CREATE USER 'culttt'@'localhost' IDENTIFIED BY "" | mysql
echo "GRANT ALL PRIVILEGES ON cribbb.* TO 'cribbb'@'localhost' IDENTIFIED BY "" | mysql
# Run artisan migrate to setup the database and schema, then seed it
php artisan migrate -env=development
php artisan db:seed -env=development

To save you the hassle of copy and pasting all of this, I’ve created a repo on GitHub that you can clone.

Now if you go to https://localhost:4567 in your browser, you should be greeted by the Laravel start page!

Conclusion

Vagrant makes creating lightweight, portable development environments easy. You can be up and running with a clean installation of Ubuntu within minutes and you can tweak and break it as much as you want.

Even if you don’t want to use Vagrant for developing, it’s still a great way to learn the intricacies of server administration. Being comfortable with setting up servers or diagnosing problems is an important aspect of being a full stack developer, and Vagrant is the perfect playground to learn your skills.

This is a series of posts on building an entire Open Source application called Cribbb. All of the tutorials will be free to web, and all of the code is available on GitHub.