How to use Vagrant?

What is Vagrant?

Vagrant makes development environments easy: creates and configures lightweight, reproducible, and portable development environments. Create a single file for your project to describe the type of machine you want, the software that needs to be installed, and the way you want to access the machine. Store this file with your project code. Then run a single command — "vagrant up" — and sit back as Vagrant puts together your complete development environment. And finally ssh into your new VM. See perfect documentation at Vagrant docs

Install Vagrant

Download the relevant package of Vagrant for your OS and install as usual. If it goes wrong, the uninstall procedure is also well described here.

Next to Vagrant, we need VirtualBox (or other virtualization platform like VMware, AWS or event KVM gets support for Vagrant). But I'll use VirtualBox, since Vagrant ships out of the box with support for it. So install VirtualBox, if not yet done. This is well documented on the Internet, I won't cover it here.

Do not expect a GUI for Vagrant, the installer simply adds vagrant to your system path so that it is available in terminals. If it is not found, log out and back. The user data for Vagrant is filed in the directory from which vagrant was used and is stored in a hidden directory named .vagrant.d.

You can check the version of vagrant you have by typing:

vagrant -v

Basics to start

Now we add a predefined OS image, and create our first VM out of it:

mkdir onevagrantproject
cd onevagrantproject
vagrant init

Then the Vagrantfile is generated. This is the only config file you'll need in order to transfer your system or development environment to others.

A `Vagrantfile` has been placed in this directory. You are now
ready to `vagrant up` your first virtual environment! Please read
the comments in the Vagrantfile as well as documentation on
`` for more information on using Vagrant.

Now an existing base image (a prepared OS image) needs to be added. This will be cloned into the new virtual machine, what you can customize.

Download a predefined Debian box:

vagrant box add cargomedia/debian-7-amd64-plain --provider virtualbox

==> box: Loading metadata for box 'cargomedia/debian-7-amd64-plain'
    box: URL:
==> box: Adding box 'cargomedia/debian-7-amd64-plain' (v0.15.0) for provider: virtualbox
    box: Downloading:
==> box: Successfully added box 'cargomedia/debian-7-amd64-plain' (v0.15.0) for 'virtualbox'!

Add the box defined above, to the Vagrantfile:

Vagrant.configure("2") do |config| = "cargomedia/debian-7-amd64-plain"

Now we can boot up the VM.

vagrant up

Bringing machine 'default' up with 'virtualbox' provider...
==> default: Importing base box 'cargomedia/debian-7-amd64-plain'...
==> default: Matching MAC address for NAT networking...
==> default: Checking if box 'cargomedia/debian-7-amd64-plain' is up to date...
==> default: Setting the name of the VM: onevagrantproject_default_1425730000283_77107
==> default: Clearing any previously set network interfaces...
==> default: Preparing network interfaces based on configuration...
    default: Adapter 1: nat
==> default: Forwarding ports...
    default: 22 => 2222 (adapter 1)
==> default: Booting VM...
==> default: Waiting for machine to boot. This may take a few minutes...
    default: SSH address:
    default: SSH username: vagrant
    default: SSH auth method: private key
    default: Warning: Connection timeout. Retrying...
    default: Vagrant insecure key detected. Vagrant will automatically replace
    default: this with a newly generated keypair for better security.
    default: Inserting generated public key within guest...
    default: Removing insecure key from the guest if its present...
    default: Key inserted! Disconnecting and reconnecting using new SSH key...
==> default: Machine booted and ready!
==> default: Checking for guest additions in VM...
==> default: Mounting shared folders...
default: /vagrant => /Users/doka/Desktop/Vagrant/onevagrantproject

Now you can ssh into the VM:

vagrant ssh

Linux debian-7-amd64-plain 3.2.0-4-amd64 d#1 SMP Debian 3.2.65-1 x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Sat Jan 17 18:59:49 2015 from

Here you have your Debian server up & running, so do what you want, install and develop, as you used to do...

To stop this VM, you can run vagrant halt to shut it down forcefully, or you can run vagrant suspend to simply suspend the virtual machine. If you are done, destroy the VM with vagrant destroy.

Build your own Vagrant box

If you do not thrust boxes out there, or need something special, or want to learn how to do it, you can build your own vagrant box as well. One can do it manually, or with some tools. There is for example the Packer, but I'll use Veewee, since it simple, works and is well documented.

Install veewee

It's a Ruby gem, so you need Ruby and can install veewee as a gem. See more details here:

gem install veewee

Create a box with veeewee

First find a template, similar to what you want to create. This is Debian for me.

veewee vbox templates | grep Debian

Then define your box

mkdir debianbox
cd debianbox
veewee vbox define 'deb78' 'Debian-7.6.0-amd64-netboot'

The basebox 'deb78' has been successfully created from the template 'Debian-7.6.0-amd64-netboot'
You can now edit the definition files stored in /Users/doka/Desktop/Vagrant/debianbox/definitions/deb78 or build the box with:
veewee vbox build 'deb78' --workdir=/Users/doka/Desktop/Vagrant/debianbox


Before build, first update the Debian image info at definitions/deb78/definition.rb, to get the latest Debian image file. Change these three line as follows, to include the Debian Wheezy 7.8 image.

:iso_file => "debian-7.8.0-amd64-netinst.iso",
:iso_src => "",
:iso_md5 => "a91fba5001cf0fbccb44a7ae38c63b6e",

Adjust memory and CPU cores at the top, but do not touch the SSH ports, unless you know what are you doing :)

Remove some config files not needed at the postinstall section, and also remove the files.

Postsintall should look like this:

:postinstall_files => [

Remove the files:

rm definitions/deb78/ definitions/deb78/ definitions/deb78/ definitions/ddeb78/

You should check and modify other files like the preseed.cfg, holding info for Debian installer, just look around.

Further options to customize:

Building the box

If you are done with customization, the build the box.

veewee vbox build 'deb78'

It will download the ISO files, but you can choose manual download as well.

Then veewee starts VirtualBox, and you can watch how automatically your Debian box is getting created. When Debian is up, the postinstall scripts are executed.

Finally, you have something like this:

The box deb78 was built successfully!
You can now login to the box with:
ssh -o UserKnownHostsFile=/dev/null -o StrictHostKeyChecking=no -p 7222 -l vagrant

Now you can make the image smaller, but I'll skip this.

Export the box and use it

veewee vbox export 'deb78'

If you want to use your own box, the go through the steps at Basics, add your box to vagrant, and update the Vagrantfile accordingly:

vagrant box add 'newserver' '/Users/doka/Desktop/Vagrant/debianbox/'

Add this snippet to Vagrantfile:

Vagrant.configure("2") do |config| = "/Users/doka/Desktop/Vagrant/debianbox/"