How to setup a (or multiple) server/LAMP-stack inside a virtual machine for local development with Vagrant and PuPHPet

You know this: You need a new server, something to develop on, something to test on, something to put your project. That’s probably the most common thing every developer faces. Usually you would

A.) setup a development environment locally, which means you install PHP, MySQL and all the stuff you need on your local machine, by hand or in pre-configured bundles (like Ampps [Win, Mac], EasyPHP [Win], WampServer [Win], SecureWAMP [Win] or even Xampp [Win, Mac, Linux]).

B.) rent a real server somewhere, for development usually something smaller, preconfigured or naked.

C.) create a virtual machine on your local machine.

THE PROBLEM WITH LOCAL DEVELOPMENT ENVIRONMENT:

As you are working on your very personal machine, you’ll have to develop all your projects, all your clients’s sites, all your tests etc. in the same environment. Change one config value and it’s activated for all your projects. Beside that, you are mixing up private projects, client’s (sensitive?) data and maybe critical tests, that may block/freeze/kill your system. Especially in linux, a wrong bash command command can kill your working system (which is your server at the same time). For Win/Mac users it’s also diffcult as the most command line options and linux tools are not directly available there.

THE PROBLEM WITH RENTED DEVELOPMENT SERVERS:

An established workflow, but this has also some big disadvantages, especially when you work for several clients: Do you want to keep a development machine for all the clients you have (and ever had) running 24/7 – and pay for the server ? Plus, handling problems, eventual attacks and pay for overtraffic ? Pro-argument: The server is usually reachable for your client, making it easy to give live-access.

THE PROBLEM WITH LOCAL VIRTUAL MACHINES:

In theory an excellent solution, as you can run a perfectly fitting server on your local machine, you have full root access, you can create masses of VMs and handle them like real server, you can also zip them away an archive them (useful for non-active projects or older clients). You can also route the IPs and ports to make them public accessable! But, it’s a shitload of work to get this to work.

VAGRANT IS THE SOLUTION !

Vagrant & PuPHPet solve exactly that problem:

Vagrant is an installable tool for Windows, Mac OS X and Linux that creates ready-to-go virtual machines, out of a simple config file. You say which linux distribution you need, what version of PHP, MySQL, Apache, modules, extensions etc, you can even define the to-be-installed packages, set passwords and create database users. All you need is a config file. You install these machines with one line on the command line (works perfectly on Windows too), start them with one command, stop them with one command, delete them with one command. You can access the machines via SSH like every other server. You can zip these “boxes” if you need space, and you can give the config file to somebody else, who will be able to create EXACTLY the same box. Perfect for team development. Killer feature: The /var/www folder (or else) can be live-synced with a local folder on your host system, so you don’t even need to login and transfer files.
PuPHPet is, as the name implies, related to Puppet (which creates and handles servers), basically it’s “a web application that allows you to easily and quickly generate custom Vagrant and Puppet controlled virtual machines”. In other words: puphpet.com is an extremely easy-to-use website that will create the Vagrant config files for you: You simply select distro, version of PHP, etc. on the site and let generate a downloadable config file, which will then install a virtual machine on your local computer. Boom!

Requirements

• VirtualBox (free for Win, Mac, Linux)! Vagrant will also run with other virtualization tools, but VirtualBox is the default use case, so let’s focus on that.
• To connect to the server you’ll need a SSH tool, sure ;)
• Windows users will need PuttyGen (to convert the ssh key) and a real ssh command line tool like Putty would also be useful. For visible FTP-like access to the server I recommend WinSCP.

Setting up the first machine

So, what will happen, basically ? We will create a config file (which is indeed a zipped folder, but more on that later) on https://puphpet.com by selecting what we want to have on our virtual machine, download that file, unzip it, open the terminal/bash/command line tool, navigate to that unzipped folder and trigger the creation of the virtual machine by just typing in one command (while being in that folder). Vagrant will create a virtual machine from the information inside that folder (some config parts will be saved by Vagrant in that folder, the virtual machine itself will be saved into VirtualBox’s virtual machine’s folder, more on that deeper in the tutorial). 3-5 minutes later you’ll have a fully installed server that is accessable via SSH and has its own IP. When you open that IP with a browser you’ll already see the well-known “It works!” page from Apache, and all the software is installed exactly as it should be.

Download and install Vagrant

Get Vagrant on http://www.vagrantup.com/ and install it on your machine.

Create a config file on Puphpet.com

puphpet.com is an extremely useful web interface for creating Vagrant config files. In this tutorial we will create a config file for LOCAL usage. But as the sites states, you could also get an account on DigitalOcean.com or Rackspace and use their servers.

Choose the OS, in this tutorial we will use Ubuntu Precise 12.04:

In the “Set Up VM Locally” box, DON’T CHANGE the Vagrant Box Name ! This name shows vagrant which operating system to download, so don’t change it manually !!! The possibility to change this form field is obviously an error in puphpet.com.

Change “Name Your Box” to something remarkable, in this tutorial we name it “box1” (to recognize the box better when using multiple VMs). The IP should stay like it is. Please note: the given standard IP ends with .101, which is perfect for our first box. When we set up more boxes, we will give them IPs like .102, .103 etc.!

Keep the rest like it is.

In the “Sharing Your Folders” box, change the “Box Sync Folder Source” from

./

to

./www

which will sync the contents of the folder “www” in your local vagrant box folder with  the /var/www folder inside your virtual machine. We will create that folder later. It should look like this now:

Leave the sections “Server Basics” and “HTTP Server” as they are – unless you know what you are doing.

In the “PHP” section, set your PHP version. Please note: PHP 5.3 is not available for Debian 7 and PHP 5.5 is not available for Debian 6. Selecting PHP 5.5 seems a good idea, and having composer on the machine is also a good idea.

Skip the rest of the PHP section (but have a look on it, these things might be interesting for you) and go to “Setup XHProf”. For this tutorial we uncheck the tick box, simply because we don’t need XHProf (and to be honest, I’m not really into the tool).

Select your timezone (might be important for database stuff).

In the “Database” section, set a MySQL root password and UNCHECK the phpmyadmin installation. Currently, in August 2013, phpmyadmin doesn’t work when installed with a puphpet-generated Vagrant config file. We will install phpmyadmin later.

Finally, let’s finish this and generate the Vagrant config file with the big button the page’s bottom.

Create a local virtual machine from Vagrant config file

Create a folder that will hold your Vagrant boxes, i named my “vm” on my D:/ drive (the development drive). Unzip your just downloaded config file here. You’ll have a “precise64” folder inside “vm” now. Rename the “precise64” folder to “box1“. I don’t know why puphpet generates folders with the distribution name, not the box name, but we don’t care yet. Honey badger.

Create a folder “www” inside the “box1” folder. The contents of “www” will be synced with /var/www of the box in realtime.

Open the command line tool / terminal (Windows users: search for cmd, in case you never worked with the command line), go into the “box1” folder and type

vagrant up

That’s it. After a short time you’ll see something like this:

Two minutes for setting up a full stack Ubuntu server. Well done, Vagrant!

Logging into the VM

Linux/Mac users can now ssh directly into the VM via [Dear readers, please verify this!]

vagrant ssh

Windows users need to open PuttyGen, then “File” -> “Load private Key” and select the “insecure_private_key” file from C:\Users\XXXXX\.vagrant.d\

Note that you need to select “All files” in the file opening screen as the “insecure_private_key” has no file ending.

Click “save private key” and save the file in the same folder, name it “my_private_vagrant_key.ppk” or something like this.

After the key is created, log into the server with WinSCP (or via Putty, if you prefer that and know how to do it): Select protocol (I use SCP), enter the IP of your VM (192.168.56.101 or .102 etc.), port stays 22, user name is “vagrant”, password keeps blank, the private key file is the file you just created. Save that stuff (for further use) and log in:

You’ll see something like this:

BOOOM! You’ve set up a real server in a virtual machine on your local pc. To prove that everything runs fine, check the installed version of PHP on the command line (Windows users: this time in putty, not the windows command line):

php -v

You should see something like “PHP 5.5.3 …“. By the way, as I’m writing this tutorial, PHP 5.5.3 has been released just a few days ago – and puphpet has provided us the very latest version of PHP already! This is really awesome, as getting up-to-date PHP versions is usually a big pain in the ass on linux. To check the Apache, simply type the VM’s IP into your browser. You’ll see the very well known Apache index page:

We are done! If you need phpmyadmin, install it with:

sudo apt-get install phpmyadmin

Stopping and deleting a VM

To stop the VM, type

vagrant halt

on the windows command line (or your host’s command line) while being into the “box1” folder. To delete the VM (this means Vagrant will really delete the full server, but leaving the config files available) type

vagrant destroy

while being in the “box1” folder. Don’t simply delete the box’s folder without destroying the box first, or you will leave dead virtual machines on your system. In case you run into problems, delete the box folder, and the according virtual machine file in VirtualBox.

The “vagrant xxx” commands only do things to the boxes in which folder you currently are.

Where does Vagrant save the VMs ?

Vagrant keeps some configs in the box’s folder (“box1”), and saves the VMs into VirtualBox’s Virtual Machines folder. Keep an eye on that, as a fresh precise64 is more than 2 GBs!

How to setup another virtual machine

Do exactly the same like before, but this time name your box “box2” on puphpet.com, give it another IP (if your first box was 192.168.56.101, then this box will be 192.168.56.102), and move the extracted files into a folder named “box2”. Open the command line, go into the folder, type

vagrant up

and your machine is running. To connect, use the IP (… .102), vagrant as username and the already created ssh key file.

Creating multiple server within ONE virtual machine

Vagrant offers the possibility to create multiple servers from one virtual machine, at least if I understand them right. This is done with “forks” of the initial snapshots of the virtual machine. However, I think to set this up for WEEKS, but totally failed. I also have never seen people working like this, so setting up a real VM for every servers seems legit.

Troubleshooting

1. Don’t change the Set Up VM Locally field manually.

2. Every box (on your machine) needs a unique “Box Name” !

3. Every box (on your machine) needs a unique IP! Setting the IPs to .101, .102 etc. seems totally valid.